E20R Directory for PMPro

=== E20R Directory for PMPro === Contributors: eighty20results Tags: pmpro, paid memberships pro, members, directory, eighty/20 results Requires at least: 4.4 Tested up to: 5.2.1 Stable tag: 3.6.3

Add a enhanced and more robust Member Directory and Profiles to your Membership Site - with attributes to customize the display.

== Description ==

The E20R Directory for PMPro plugin enhances your membership site with a public or private, searchable member directory and member profiles.

This plugin creates 2 short codes for a Member Directory and Member Profile pages, which can be defined in Memberships > Settings > Pages of the WordPress admin.

It has support for a number of additional attributes/features beyond what the PMPro add-on offers (see list).

Unlike the PMPro add-on, this version of the member directory supports multiple directory/profile page combinations. As a result, it's possible to configure more than one "Directory" page and have it linked to it's own "Profile" page. This means you can create multiple directories with different settings. One use case is to have People and Business memberships where the People directory consists solely of users/members. The "Business directory", on the other hand, consists solely of businesses.

With the activation of this plugin, you will see a Billing Address and Shipping Address section on the user's WordPress profile page (backend). This section will let your members update their PMPro billing and shipping address(es).

The shipping address section is only available if the PMPro Shipping Address add-on is installed and active (or has been).

The [pmpro_member_directory] and [pmpro_member_profile] short codes are fully supported.

Credit: Loosely based on the PMPro Member Directory and Profiles add-on from the Paid Memberships Team.

=== Shortcodes === Shortcode attributes for [e20r-member-directory] include:

1. avatar_size: The square pixel dimensions of the avatar to display. Requires the "show_avatar" attribute to be set to 'true'. default: '128' (accepts any numerical value).
2. fields: Display additional user meta fields. default: none (accepts a list of label names and field IDs, i.e. fields="Company,company;Website,user_url").
3. layout: The format of the directory. default: div (accepts 'table', 'div', '2col', '3col', and '4col').
4. levels: The level ID or a comma-separated list of level IDs to include in the directory. default: all levels (accepts a single level ID or a comma-separated list of IDs).
5. paginated: Whether to use pagination or not (default: true )
6. page_size: The number of records per page in a paginated display (default: 15)
7. link: Optionally link the member directory item to the single member profile page. default: true (accepts 'true' or 'false').
8. order: Sort the results based on the order_by attribute in ascending or descending order. default: ASC (accepts 'DESC' or 'ASC').
9. order_by: The sort order for the results. default: 'display_name' (accepts 'user_email', 'display_name', 'user_login', 'user_registered', 'membership_id', 'startdate', 'joindate', 'last_name', 'first_name' )
10. show_avatar: Display the user's avatar generated via Gravatar (https://en.gravatar.com) or user-submitted using a plugin like Simple Local Avatars (https://wordpress.org/plugins/simple-local-avatars/); default: true (accepts 'true' or 'false').
11. show_email: Display the user's email address; default: true (accepts 'true' or 'false').
12. show_level: Display the user's membership level; default: true (accepts 'true' or 'false').
13. show_search: Display a search form (searches on member display name or email address); default: true (accepts 'true' or 'false').
14. show_startdate: Display the user's membership start date for their current level; default: true (accepts 'true' or 'false').
15. show_roles: Display the users if they have been assigned the role(s) listed (default: null, accepts comma separated list of role names)
16. members_only_link: Show the link to the profile details page to logged in and active members only (default: 'false', accepts 'true' or 'false')
17. editable_profile: If the user is logged in, they are shown both a view and edit link for their profile page (default: 'false', accepts 'true' or 'false'). Caution: The edit link may direct the user to the WordPress backend unless a front-end profile plugin is installed (For example: Theme My Login)
18. profile_page_slug: The page slug for the profile page to send the viewer to if they click on the profile for a user. (This will also allow multiple profile and directory pages on the same site).
19. filter_key_name: Allows filtering of the directory based on the User Meta key and value (for instance a Register Helper field name and value). This attribute must be used together with the 'filter_key_value' attribute.
20. filter_key_value: Allows filtering of the directory based on the User Meta key and value (for instance a Register Helper field name and value). This attribute must be use together with the 'filter_key_name' attribute.

Shortcode attributes for [e20r-member-profile] include:

1. avatar_size: The square pixel dimensions of the avatar to display. Requires the "show_avatar" attribute to be set to 'true'. default: '128' (accepts any numerical value).
2. fields: Display additional user meta fields. default: none (accepts a list of label names and field IDs, i.e. fields="Company,company;Website,user_url").
3. show_avatar: Display the user's avatar generated via Gravatar (https://en.gravatar.com) or user-submitted using a plugin like Simple Local Avatars (https://wordpress.org/plugins/simple-local-avatars/); default: true (accepts 'true' or 'false').
4. show_bio: Display the user's bio (if available); default: true (accepts 'true' or 'false').
5. show_billing: Display the user's billing address (if available); default: true (accepts 'true' or 'false').
6. show_email: Display the user's email address; default: true (accepts 'true' or 'false').
7. show_level: Display the user's membership level; default: true (accepts 'true' or 'false').
8. show_phone: Display the user's billing phone (if available); default: true (accepts 'true' or 'false').
9. show_search: Display a search form (searches on member display name or email address); default: true (accepts 'true' or 'false').
10. show_startdate: Display the user's membership start date for their current level; default: true (accepts 'true' or 'false').
11. user_id: Show a specific member's profile; default: none (accepts any numeric uesr id, i.e. user_id="125").
12. billing_address: Show the PMPro Billing information in a separate section of the profile page. Default: 'false' (accepts 'true' or 'false'). The default heading for the section is "Billing Address", but can be modified with the 'e20r-directory-profile-billing-header' filter. The filter returns the text of the heading.
13. shipping_address: Show the PMPro Shipping information in a separate section of the profile page. Default: 'false' (accepts 'true' or 'false'). The default heading for the section is "Shippping Address", but it can be modified with the 'e20r-directory-profile-shipping-header' filter. The filter returns the text of the heading.
14. directory_page_slug: The page slug for the directory page to use when allowing a user to return (This will also allow multiple profile and directory pages on the same site)

== Installation ==

1. Upload the e20r-directory-for-pmpro directory to the /wp-content/plugins/ directory of your site.
2. Activate the plugin through the Plugins menu in WordPress.
3. Create a page for your directory and set the appropriate shortcode attributes and Require Membership settings per your needs.
4. Create a page for your profile and set the appropriate shortcode attributes and Require Membership settings per your needs.
5. Navigate to Memberships > Page Settings to assign your pages to the Directory and Profile page settings.

== Examples ==

Show only level IDs 1 and 4, hide avatars and email address: [e20r-member-directory levels="1,4" show_avatar="false" show_email="false"]

Show all level IDs, hide level name and start date: [e20r-member-directory show_level="false" show_startdate="false"]

Show a unique member directory by level. Level 1 Members can only see other Level 1 Members...: [membership level="1"] [e20r-member-directory levels="1"] [/membership]

[membership level="2"] [e20r-member-directory levels="2"] [/membership]

[membership level="3"] [e20r-member-directory levels="3"] [/membership]

Show unique member profiles based on level - hide user phone number and email address for member listings belonging to membership level ID 1. Show the same data for membership levels belonging to membership level ID 2.

Using a single page, but with the [membership] short code, you can modify views for logged in users

On (fake) Page #1 (show to visitors who haven't logged in): [membership level="-l"] [e20r-member-directory levels="1" show_email="false" show_phone="false"] [/membership]

On Page #2 (show to logged in users): [membership level="l"] [e20r-member-profile levels="2" show_email="true" show_phone="true"] /[membership]

OR, you can use completely separate page(s) for the two level specific directory short codes and their corresponding member profile pages to display member level specific directories. See the "Membership" -> "Settings" -> "Page Settings" page to configure multiple directories/profiles for the site.

== Hooks & Filters == === Filters ===

1. e20r-member-profile_shipping_header - Set the heading for the Shipping Information section (if applicable). default: 'Billing Address' - string
2. e20r-member-profile_billing_header - Set the heading for the Billing Information section (if applicable). default: 'Shipping Address' - string
3. pmpromd_extra_search_fields - List (array) of user meta data keys that will have added search input sections on the directory page - default: array() (empty array)
4. pmpromd_exact_search_values - Whether to wrap the search input in wildcard during DB operation, or use the extact string as typed - default: false (boolean)
5. pmpromd_membership_statuses - Membership statuses to include in the search result. Default behavior is to only included active member(s) - default: array( 'active' )
6. e20r-directory-for-pmpro_set_order - Directly change the directory search result order (SQL).
7. e20r-directory-for-pmpro_sql - Modify the SQL statement used to search for whom to include in the directory listing
8. e20r-directory-for-pmpro_search_class - Add extra CSS class(es) to the directory listing - default: null
9. pmpromd_search_placeholder_text - Change the placeholder text in the Search input field - default: "Search Members" - string
10. e20r-directory-for-pmpro_extra_search_input - Add array of HTML to add extra search input fields (and field types) below the main "Search" input.
11. e20r-member-profile_fields - Allow user to remove/add additional usermetadata fields & labels programatically
12. e20r-directory-for-pmpro_non_admin_profile_settings - Set to false in order to hide the "Hide from Member Directory?" setting on the user's WordPress profile page, unless they're assigned the administrator role.
13. 'e20r-directory-for-pmpro_included_levels' - Allow admin to configure which membership level(s) to include for directory
14. 'e20r-directory-for-pmpro_metafield_value' - Used to format/modify the displayed usermeta value (Register Helper field value). Useful when using select/select2 fields and you need to translate a value to a label or if the stored value consists of an array. In that case, the default behavior is to let the value to display as a comma-separated list).
15. e20r-directory-for-pmpro_profile_show_return_link - Allow hiding the "View All Members" link on/from the Member Profile page (template).

=== Action hooks ===

1. e20r-directory-for-pmpro_extra_search_output - Output HTML so a user can provide input for the specified pmpromd_extra_search_fields search fields
2. e20rmd_add_extra_profile_output - By default used to output the Shipping & Billing information sections on the user profile page, but can be used to add more data to the profile page for the user. Passes the current user's WP_User object as well as the array of entries from the 'fields=""' attribute (as it was prior to having been passed through the 'e20r-member-profile_fields' filter).
3. e20rmd_add_extra_profile_output - Output HTML at the bottom of the profile page entry for the selected member. Accepts 2 arguments: $real_fields_array (array of fields from Register Helper) and $profile_user (WP_User object for the member/user)
4. e20rmd_add_extra_directory_output - Output HTML at the bottom of the directory entry for the current user. Accepts 2 arguments: $real_fields_array (array of fields from Register Helper) and $the_user (WP_User object for the member/user)

NOTE: e20r-directory-for-pmpro_extra_search_input (filter hook) and e20r-directory-for-pmpro_extra_search_output (action hook) are two ways - hooks - of achieving the same thing (the filter is for backwards compatibility reasons). The preferred approach at this point is to use the e20r-directory-for-pmpro_extra_search_output action hook.

== Frequently Asked Questions ==

= I found a bug in the plugin. =

Please post it in the issues section of GitHub and we'll fix it as soon as we can. Thanks for helping. https://github.com/eighty20results/e20r-directory-for-pmpro/issues

= I need help installing, configuring, or customizing the plugin. =

Please visit our premium support site at http://www.eighty20results.com for more documentation and our support forums.

== Changelog ==

= 3.6.3 =

• BUG FIX: Redirecting a profile view to the directory page for the wrong reasons

= 3.6.2 =

• BUG FIX: Attempted to process profile preheader on a non-page
• BUG FIX: Refactored profile shortcode check
• BUG FIX: Error in regex for level(s)

= 3.6.1 =

• BUG FIX: Load utils library ear