Simple:Press Documentation

Plugin: Custom Profile Fields

Plugin Description

Plugin: Custom Profile Fields – This Simple:Press plugin allows creation of additional personalized custom profile fields for forum members where their preferences can be indicated. The indicated member preferences can then be displayed to other users on the forum pages.

Plugin Features

Installing this plugin adds:

  • a new “Custom Profile Fields” section to the “Available Plugins – Install Simple:Press Plugins” panel under the forum Admin menu entry “Plugins” > “Available Plugins”. From this panel the Custom Profile Fields plugin can be activated, deactivated, uninstalled, deleted, and its options set up using its “Activate/Delete” and “Deactivate/Uninstall/Options” selections. The Options link goes to the new “Profiles – Custom Profile Fields” panel where the the admin sets up the custom profile fields and their options from which users may select.

Activating this plugin provides:

  • a new sub-menu “Profile Custom Fields” entry under the forum Admin menu entry “Profiles” linked to the new “Profiles – Custom Profile Fields” panel where the custom fields the admin specifies are set. “Help” links are provided and should be consulted.
  • a new entry in one of the forms (tabs, sub-pages) in the user profile as specified by the forum Admin for each custom profile field input on the “Profiles – Custom Profile Fields” panel. The forum Admin selects from the drop down menu under “Profile Form For Display”.
    • If users display their profile and see a page containing a custom profile field set up by the forum Admin, the users can make selections or provides appropriate inputs for the custom profile fields on that page.
  • The users selections / inputs can then be displayed in various forms and on various forum pages by the forum admin selectively adding the three (3) custom profile field’s template tags to the active theme’s template files.
    • None of the template tags are currently in the supplied standard Simple:Press themes.

There are no new permissions added to the permission sets due to this plugin.

Plugin Requirements

Requires Simple:Press version 5.5.5 and above.

The plugin must be installed, activated, and its options set up before it is operational.

As part of the installation, a “Custom Profile Fields” section is added to the “Available Plugins – Install Simple:Press Plugins” panel under the forum Admin menu Plugins > Available Plugins. From this panel the Custom Profile Fields plugin can be activated, deactivated, uninstalled, deleted, and its options set up using its “Activate/Delete” and “Deactivate/Uninstall/Options” selections. The Options link goes to the new Profiles – Custom Profile Fields panel where the options are set.

There are no new permissions added to the permission sets due to this plugin.

The plugin has 3 template tags, but none are included in current standard themes. If any of the template tags are to be added,

  • It is recommended that a Custom or Child Theme be created first with the structure and files to receive the template tags before installing this plugin.
  • It is also recommended that the template tag be called conditionally, if (function_exists(‘…’), so the website will continue to operate if the Custom Profile Field plugin is deactivated or removed.

Installation and Activation

Please see Using Plugins on how to obtain and install the Simple:Press Custom Profile Fields plugin.

As mentioned there the default location for Simple:Press plugin folders is …/wp-content/sp-resources/forum-plugins. If this path is changed, it is important to note that the plugin’s folder and its content need to reside in the forum plugins folder wherever it has been moved and however it has been renamed. See Storage Locations for more information.

Activation is accomplished from the Admin Dashboard panel menu at Forum > Plugins > Available Plugins from the drop down Forum Admin menu. On the “Available Plugins – Install Simple:Press Plugins” panel select the “Custom Profile Fields” plugin and click on “Activate”. The “Activate/Delete” label changes to “Deactivate/Uninstall/Options”. To deactivate the plugin, click on “Deactivate”. The “Deactivate/Uninstall/Options” label changes to “Activate/Delete”.

Plugin Administrative Options

After activation, a) on the aforementioned “Available Plugins – Install Simple:Press Plugins” panel, click “Options” on the “Custom Profile Fields” plugin section or b) from the forum Admin menu select Forum > Profiles > Profile Custom Fields sub-menu item to get the “Profile – Custom Profile Fields” panel with “Custom Profile Field” section.

  • Creating a “Custom Profile Field”
    • It is worth noting that any custom profile fields defined here will only be available in the forum profile and not in the WordPress profile (unless another WP plugin can use the Simple:Press Custom Profile Field plugin’s template tag whose call displays the custom profile field).
    • Under the “Name” column, start creation of a custom field by entering a name for the custom field. The example below uses “Game Type”.
    • Under the “Type” column after clicking on the down arrowhead to have the options shown in a drop down menu, select one of the options by highlighting it. The example below uses “Select”.
      • The custom field types currently allowed are a check-box, an input box, a text-area, a select box, a list,  or a radio group.
    • Under the “Value” column if the “Type” is “Select”, “List’ or “Radio”, input the values to be shown as the options for the users to select in their profiles. The values are separated by a comma forming a comma separated list. The example below uses “xbox,wii,ps3”.
      • The values field is only valid for a type of “Select”, “List’, or “Radio” and is ignored otherwise.
    • Under the “Profile Form For Display” column, after clicking in the selection box to have the options shown in a drop down menu, choose the user profile form (page) on which to show the custom field. The example below uses “Edit Identities”.
        • Note: this is only the location where the users can make selections/inputs when viewing/editing their profiles.
        • The entries in the drop down menu can expand depending on which profile options and Simple:Press plugins are active. An example of some of the options is:
          • Don’t display
          • Overview
          • Edit Profile
          • Edit Identities
          • Edit Photos
          • Account Settings
          • Manage Buddies
          • Manage Adversaries
          • Edit Global Options
          • Edit Posting Options
          • Manage Watches
          • Show Permissions
          • Subscription Options
          • Topics Subscriptions
          • Forum Subscriptions

       

        • Save the custom profile field by clicking the “Update” button at the bottom of the panel. After saving the custom field, the form will reload and another custom filed can be entered using the same steps as above.

       

    • Example – Create Custom Profile Field for Video Game Owned
        • Provide users a way to add what video game they use by adding this custom profile field to their profile. Create the new custom profile field with the name of the game platform and a selectable list of which game they own.

      screenshot_01

        • In the above example the list was added to the “Edit Identities” form. Once added there will be a new selection box displayed where the user can select from the values set up by the forum Admin.

      screenshot_02

      • Please note, that on this panel, the custom field is only being created. After creating the custom field, it must be decided how and where it is viewed on the forum pages as discussed next.

After setting up a Custom or Child Theme, where and how the custom profile field data is displayed is determined by the placement of the Custom Profile Field plugin’s template tags on the theme’s pages and who is to see the information.

    • Determining the value to use for ‘$userid’ in the Template Tags
      • The ‘$userid’ parameter in the plugin’s template tags determines whose information is to be shown to whom.
      • Each of the template tag examples immediately below shows the parameter’s selection using the Video game Custom Profile Field example developed above.
      • Depending on who is to view the custom profile field content and where it is to be displayed influences selection of the parameter’s value. The plugin’s ‘sp_CustomProfileFieldsDisplay()’ template tag is used in the examples.
      • An example of showing a custom field for a user under his avatar in forum posts could be:
        sp_CustomProfileFieldsDisplay($name, $spPostUser->ID);
      • An example of showing the Custom profile display to the current logged in user could be:
        sp_CustomProfileFieldsDisplay($name, $spTheUser->ID);
      • An example of showing the Custom profile display of a user in the user’s profile pages could be:
        sp_CustomProfileFieldsDisplay($name, $spProfileUser->ID);
    • Determining where to place the Template Tags
      • The placement of the plugin’s template tag in the active theme’s files determines where the custom profile field information will be shown.
      • Each template tag is individually discussed in a section below. The example for each template tag uses the Video game Custom Profile Field developed above and shows a possible placement of the template tag in a theme file.
    • Using the Custom Field Slug
      • The custom field slug can be used to obtain and return or display the information.
      • Using the Video Game example one could ‘echo’ or display the game type using:
        echo $spThisPostUser->gametype;

It is worth noting that any custom profile fields defined here will only be available in the forum profile and not in the WordPress profile (unless another WP plugin can use the Simple:Press Custom Profile Field template tags).

Plugin Language Translation

A plugin’s message strings can be translated from English to other languages and then the translation displayed if language translation files are available. Some plugins may not have such files.

Information regarding downloading language files, “mo’ language file placement, and translation (language localization) is found at Localization.

More information is available regarding translation files at Simple:Press Translations. On the base page, select the “Getting Started Guide” link for basics about it’s use. On that page, select the “register a username here” link to obtain a password to the site. Use the “Contact Form” link to request the desired language if it is not currently available. The “Contact Form” link may also be used to volunteer to be a validator for a translation project.

The Custom Profile Fields plugin’s available language translation files with translation statistics, and message translations can be viewed at Custom Profile Fields Translations. Select the Version link to see the languages available. Select the link for the desired language to see forum messages and their available translations. If available, export the file for the selected language to its proper forum language sub-folder as a “mo” file using the export link at the bottom of the page displaying the actual message translations for the language selected.

The default location for plugin language files is …/wp-content/sp-resources/forum-language/sp-plugins. If this path is changed, it is important to note that the plugin’s language file needs to reside in the language sub-folder for sp plugins wherever it has been moved and however it has been renamed. See Storage Locations for more information.

Plugin Usage

Forum Admins use this plugin to:

  • Set up the Custom Profile Fields the users are to make selections from on their individual profile pages.
  • Determine which template tag to use and on which theme page to display the selections made by the users.

Forum users use this plugin to:

  • Make their selections from the options set up by the forum Admin in the Custom Profile Fields. The options show up on the forum users’ profile forms/pages as specified by the setting in the “Profile Form For Display” column when the Custom Profile Field was developed by the forum Admin.
  • Observe their selections and selections of other users on the various forum pages as set up by the forum Admin through selection of the plugin’s template tag parameters as well as their placement in theme pages.
  • Viewing Custom Profile Fields displayed via the ‘sp_CustomProfileFieldsProfileDisplay’ template tag
  • From the forum page, click on the “Members” button generally found in the forum page header to view the “Members List” page with summary sections for each forum user.
  • On the “Members List” page, find the summary section for the individual forum user whose profile is to be displayed.
  • Within that forum user’s summary section, under “Member Actions” click on the “profile icon” to see the forum user’s “profile popup page”.
    • Note: When hovering the cursor over the “profile icon”, the tooltip message “Profile” is displayed.
    • If the forum Admin placed a template tag function call in the theme’s ‘spProfilePopupShow.php’ file, user selections for the Custom Profile Field specified in the function call will show up on this popup page.
  • On the forum user’s “profile popup page” near the bottom of the page, click on the “View Full Profile for X” button, where “X” is the forum user’s name, to see the forum user’s “full profile page”.
    • If the forum Admin placed a template tag function call in the theme’s ‘spProfileShow.php’ file, user selections for the Custom Profile Field specified in the function call will show up on this full profile page.

Template Tags Used in the Plugin

There are three (3) template tags available for this plugin that allow further customization of the plugin’s usage or otherwise customize the website. The Template Tag can be viewed by selecting its link below.

Action and Hooks Used in the Plugin

There are Actions and Hooks available in the Plugin’s Template Tags. The Template Tag’s Action and Hooks can be viewed by selecting its link below.

There are other Actions and Hooks available for this plugin.

In file sp-custom-profile-fields-components.php

  • apply_filters(‘sph_custom_profile_fields_’.$fields[‘slug’], $tout); – Allows modification of the custom profile filed display code just prior to being output/returned.

Plugin and Template Tag Changelog

Since Simple:Press version 5.0.
Version 5.5.5 and Plugin version 1.3.3: Added the sp_CustomProfileFieldsProfileDisplay() template tag.

Codex page sync’d to code version 5.5.5 and plugin version 1.3.3.



Individual Template Tags


 

sp_CustomProfileFieldsDisplay

Description

sp_CustomProfileFieldsDisplay() – This template tag displays the selections made by users on their profile pages to Custom Profile Field options set up by the forum Admin.

Usage

sp_CustomProfileFieldsDisplay($name, $userid=0);

Arguments

$name – Name of the Custom Profile Field to be displayed. This is the text input by the forum Admin under the “Name” column for the Custom Profile field.
Type:
(string) (optional)
Default:
None

$userid – Id of the user whose selection(s) from the Custom Profile Field options will be displayed.
Type:
(string) (optional)
Default:
0

Special Notes

This template tag function requires the usage of the sp-custom-profile-fields-display-tag.php file located in the plugin’s template-tag folder.
This template tag is not provided in standard supplied Simple:Press themes. If it is to be used in a theme:

  • It is recommended that a Custom or Child Theme be created first with the structure and files to receive the template tags before installing this plugin.
  • It is also recommended that the template tag be called conditionally, if (function_exists(‘…’), so the website will continue to operate if the Custom Profile Field plugin is deactivated or removed.

Examples

Using the Video game example above, conditionally display the video game owned by a member below the member’s avatar and name in every one of the member’s forum posts. In this example, if a member had selected “wii”, then display “wii” in each of the member’s posts under the member’s avatar and name. The template tag is put in the theme’s ‘spTopicView.php’ file under the Avatar and name display calls.

Locate the following code in spTopicView.php

sp_UserAvatar('tagClass=spPostUserAvatar spCenter&context=user', $spThisPostUser);
sp_PostIndexUserName('tagClass=spPostUserName spCenter');
sp_PostIndexUserLocation('tagClass=spPostUserLocation spCenter');

In the code insert a comment and the conditional call as shown below:

sp_UserAvatar('tagClass=spPostUserAvatar spCenter&context=user', $spThisPostUser);
sp_PostIndexUserName('tagClass=spPostUserName spCenter');
# Added poster's game type selection to the forum post, poster information section.
if (function_exists('sp_CustomProfileFieldsDisplay')) sp_CustomProfileFieldsDisplay('Game Type', $spThisPostUser->ID);
sp_PostIndexUserLocation('tagClass=spPostUserLocation spCenter');

 

Actions and Hooks Used in the sp_CustomProfileFieldsDisplay Template Tag

  • None.

Changelog

See Plugin and Template Tag Changelog for Template Tag changes and Codex page syncing to code versions.


 

sp_CustomProfileFieldsDisplayExtended

Description

sp_CustomProfileFieldsDisplayExtended() – This template tag displays the selections made by users on their profile pages to Custom Profile Field options set up by the forum Admin along with additional information as specified in the tag’s parameters.

Usage

sp_CustomProfileFieldsDisplayExtended($args, $name, $userid=0, $label=”);

Arguments

$args – List of arguments for controlling display.
Type:
(string) (optional)
Default:
‘tagClass’ => ‘spCustomField’
‘labelClass’ => ‘spCustomLabel’
‘labelSep’ => ‘: ‘
‘before’ => ”
‘after’ => ”
‘listSep’ => ‘, ‘
‘echo’ => 1

‘tagClass’: CSS Class applied to the container for styling.
‘labelClass’: CSS Class applied to the optional label.
‘labelSep’: Text to be displayed between the optional label and the data from the Custom Profile Field. This text item can include allowed HTML.
‘before’: Text to be displayed before the optional label and the data from the Custom Profile Field. This text item can include allowed HTML. This argument could be used to display an image or icon.
‘after’: Text to be displayed after the optional label and the data from the Custom Profile Field. This text item can include allowed HTML. This argument could be used to display an image or icon.
‘listSep’: Text to be display between each item if there is a list. This text item can include allowed HTML.
‘echo’: Flag to indicate whether to write out the generated html display code or just return the html display code. One (1) is true and causes the html display code to be written to the display. Zero (0) is false and causes the html display code to be returned instead of written out.

$name – Name of the Custom Profile Field to be displayed. This is the text input by the forum Admin under the “Name” column for the Custom Profile field.
Type:
(string) (optional)
Default:
None

$userid – Id of the user whose selection(s) from the Custom Profile Field options will be displayed.
Type:
(string) (optional)
Default:
0

$label – Text to be displayed as the label.
Type:
(string) (optional)
Default:
None

Special Notes

This template tag function requires the usage of the sp-custom-profile-fields-display-tag.php file located in the plugin’s template-tag folder.
This template tag is not provided in standard supplied Simple:Press themes. If it is to be used in a theme:

  • It is recommended that a Custom or Child Theme be created first with the structure and files to receive the template tags before installing this plugin.
  • It is also recommended that the template tag be called conditionally, if (function_exists(‘…’), so the website will continue to operate if the Custom Profile Field plugin is deactivated or removed.

Examples

Using the Video game example above and the default arguments, conditionally display the video game owned by a member along with the ‘label’ of “GAMES” below the member’s avatar and name in every one of the member’s forum posts. In this example, if a member had selected “wii”, then display “GAMES:wii”. The template tag is put in the theme’s spTopicView.php file under the Avatar and name display calls.

Locate the following code in spTopicView.php

sp_UserAvatar('tagClass=spPostUserAvatar spCenter&context=user', $spThisPostUser);
sp_PostIndexUserName('tagClass=spPostUserName spCenter');
sp_PostIndexUserLocation('tagClass=spPostUserLocation spCenter');

In the code insert a comment and the conditional call as shown below:

sp_UserAvatar('tagClass=spPostUserAvatar spCenter&context=user', $spThisPostUser);
sp_PostIndexUserName('tagClass=spPostUserName spCenter');
# Added poster's game type selection with expanded text to the forum post, poster information section.
if (function_exists('sp_CustomProfileFieldsDisplayExtended')) sp_CustomProfileFieldsDisplayExtended('', 'Game Type', $spThisPostUser->ID, 'GAMES');
sp_PostIndexUserLocation('tagClass=spPostUserLocation spCenter');

 

Actions and Hooks Used in the sp_CustomProfileFieldsDisplayExtended Template Tag

  • None

Changelog

See Plugin and Template Tag Changelog for Template Tag changes and Codex page syncing to code versions.


 

sp_CustomProfileFieldsProfileDisplay

Description

sp_CustomProfileFieldsProfileDisplay() – This template displays a custom profile field IN either the profile popup or profile pages viewed via the forum ‘Members List’ page. It performs all the standard html creation to fit the pattern of the standard profile information display.

Usage

sp_CustomProfileFieldsProfileDisplay($name, $userid=0, $label=”);

Arguments

$name – Name of the Custom Profile Field to be displayed. This is the text input by the forum Admin under the “Name” column for the Custom Profile field.
Type:
(string) (optional)
Default:
None

$userid – Id of the user whose selection(s) from the Custom Profile Field options will be displayed.
Type:
(string) (optional)
Default:
0

$label – Text shown as the label custom field.
Type:
(string) (optional)
Default:
None

Special Notes

This template tag function requires the usage of the sp-custom-profile-fields-display-tag.php file located in the plugin’s template-tag folder.
This template tag is not provided in standard supplied Simple:Press themes. If it is to be used in a theme:

  • It is recommended that a Custom or Child Theme be created first with the structure and files to receive the template tags before installing this plugin.
  • It is also recommended that the template tag be called conditionally, if (function_exists(‘…’), so the website will continue to operate if the Custom Profile Field plugin is deactivated or removed.

The profile popup page and the profile page are viewed via the forum ‘Members List’ page displayed when the “Members” button is selected.

  • The template tag is used on the theme’s ‘spProfilePopupShow.php’ file to display on the member’s profile popup page.
  • The template tag is used on the theme’s ‘spProfileShow.php’ file to display on the member’s profile page.

Examples

Displaying on the Member’s Profile Popup Page
Using the Video game example above, conditionally display the video game owned by a member preceded by the text “Game Type Owned” at the bottom of the forum user’s “Statistic” section on the forum user’s profile popup page. In this example, if the forum user had selected “wii”, then display “Game Type Owned: wii” on the profile popup page. The template tag would be put in the theme’s ‘spProfilePopupShow.php’ file at the end of the section.

Locate the following code in the theme’s ‘spProfilePopupShow.php’ file.

		sp_ProfileShowSearchPosts('', __sp('Search User Posts'), __sp('Topics Started'), __sp('Topics Posted In'));
	sp_ColumnEnd('', 'profileStats');
sp_SectionEnd('tagClass=spClear', 'profileDetails');

In the code insert a comment and the conditional call as shown below:

		sp_ProfileShowSearchPosts('', __sp('Search User Posts'), __sp('Topics Started'), __sp('Topics Posted In'));
		# Added forum user's game type selection into profile popup  
		if (function_exists('sp_CustomProfileFieldsProfileDisplay')) sp_CustomProfileFieldsProfileDisplay('Game Type', $spProfileUser->ID, 'Game Type Owned');
	sp_ColumnEnd('', 'profileStats');
sp_SectionEnd('tagClass=spClear', 'profileDetails');

Displaying on the Member’s Profile Page
Using the Video game example above, conditionally display the video game owned by a member preceded by the text “Owns” at the bottom of the forum user’s “Statistic” section on the forum user’s full profile page. In this example, if the forum user had selected “wii”, then display “Owns: wii” on the full profile page. The template tag would be put in the theme’s spProfilePopup.php file at the end of the section.

Locate the following code in the theme’s spProfileShow.php file.

		sp_ProfileShowSearchPosts('', __sp('Search User Posts'), __sp('Topics Started'), __sp('Topics Posted In'));
	sp_ColumnEnd('', 'profileStats');
sp_SectionEnd('tagClass=spClear', 'profileDetails');

In the code insert a comment and the conditional call as shown below:

		sp_ProfileShowSearchPosts('', __sp('Search User Posts'), __sp('Topics Started'), __sp('Topics Posted In'));
		# Added forum user's game type selection into the full profile page  
		if (function_exists('sp_CustomProfileFieldsProfileDisplay')) sp_CustomProfileFieldsProfileDisplay('Game Type', $spProfileUser->ID, 'Owns');
	sp_ColumnEnd('', 'profileStats');
sp_SectionEnd('tagClass=spClear', 'profileDetails');

 

Actions and Hooks Used in the sp_CustomProfileFieldsProfileDisplay Template Tag

  • None.

Changelog

See Plugin and Template Tag Changelog for Template Tag changes and Codex page syncing to code versions.

More Topics In SimplePress: Plugins


Copyright © 2006-2019 Simple:Press. All Rights Reserved.