Grant Program Access Control

Requires WordPress: 5.0+
Tested up to: 6.7
License: GPL v2 or later

Description

Grant Program Access Control is a WordPress plugin that restricts access to content based on user roles mapped to grant program taxonomy terms. It provides fine-grained content filtering for organizations managing multiple grant programs, ensuring users only see content relevant to their assigned programs.

Features

• Role-Based Access Control: Map WordPress user roles to specific grant programs
• Flexible Filtering: Choose which post types are filtered by grant program access
• Universal Access: Tag content as "all-grants" to make it visible to all logged-in users
• Unrestricted Access: Assign roles "All Content" access to bypass all restrictions
• Multiple Integration Points:
  • Native WordPress archive queries
  • Bricks Builder query loops
  • FacetWP filtering and facets
  • Pie Calendar event listings
• Single Post Protection: Direct URL access is restricted based on grant program
• Public Homepage: Login page remains accessible to non-authenticated users

Installation

1. Upload the grant-program-access-control folder to /wp-content/plugins/
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Navigate to Access Control in the WordPress admin menu
4. Configure your settings (see Configuration section below)

Configuration

1. Filtered Post Types

Choose which custom post types should be restricted by grant program access:

1. Go to Access Control in the WordPress admin menu
2. Under Filtered Post Types, check the post types you want to filter
3. Common choices: Resources, Grants, Trainings, Events
4. Unchecked post types will be accessible to all logged-in users

2. Role to Grant Program Mapping

Map each user role to a grant program:

1. Go to Access Control → Role to Grant Program Mapping
2. For each role, select from the dropdown:
   • Specific Grant Program: Users see only content from their assigned program + "all-grants" content
   • All Content (No Restrictions): Users see everything regardless of grant program (useful for specialists, editors)
   • No Grant Program: Users have no special access

Example Configuration:

oifsp-user → OIFSP
bhwet-para-user → BHWET-Para
bhwet-pro-user → BHWET-Pro
ta_specialist → All Content (No Restrictions)

3. Grant Program Taxonomy

The plugin uses the grant-program custom taxonomy. Content should be tagged with:

• Specific program terms (e.g., oifsp, bhwet-para, bhwet-pro)
• all-grants - Special term that makes content visible to ALL logged-in users regardless of role

How It Works

Access Rules

1. Homepage: Public and accessible to everyone
2. Other Pages: Require login
3. Filtered Post Types:
   • Archive pages are filtered by user's grant program
   • Single posts check grant program before allowing access
   • Unauthorized access redirects to /no-access/ page
4. Non-Filtered Post Types: Accessible to all logged-in users
5. Administrators: Always bypass all restrictions

Content Visibility

Users can see content if:

• Tagged with their assigned grant program, OR
• Tagged with "all-grants" (universal access), OR
• Has no grant-program tags (general content), OR
• User's role is set to "All Content (No Restrictions)"

Integration Points

The plugin automatically filters queries from:

• WordPress Core: pre_get_posts hook filters archive queries
• Bricks Builder: bricks/posts/query_vars hook filters query loops
• FacetWP: facetwp_query_args hook filters search results and facet counts
• Pie Calendar: piecal_event_query_args hook filters event listings

User Role Naming Convention

The plugin expects user roles to follow this pattern:

• Project Directors: {program-slug}-user (e.g., oifsp-user)
• Project Officers: {program-slug}-project-officer (e.g., oifsp-project-officer)
• Specialists: Any role containing specialist (e.g., ta_specialist)

This naming convention is used by the companion user profile display functionality.

ACF Integration

The plugin works with Advanced Custom Fields (ACF) relationship fields:

• Grant to Director: grant_to_director_relationship (User field on Grant CPT)
• Grant to Officer: grant_to_officer_relationship (User field on Grant CPT)

These fields store serialized arrays of user IDs and are queried using LIKE comparison.

Helper Functions

gpac_user_can_view_post()

Check if a user can view a specific post:

$can_view = gpac_user_can_view_post($post_id, $user_id);
if ($can_view) {
    // Display content
}

Parameters:

• $post_id (int|null) - Post ID to check (defaults to current post)
• $user_id (int|null) - User ID to check (defaults to current user)

Returns: bool - True if user can view the post

gpac_get_user_programs()

Get array of grant programs a user can access:

$programs = gpac_get_user_programs($user_id);
// Returns: ['oifsp', 'all-grants'] or 'all' for unrestricted access

Parameters:

• $user_id (int|null) - User ID (defaults to current user)

Returns: array|string - Array of program slugs, or 'all' for unrestricted access

Bricks Dynamic Data Tag

Use in Bricks Builder conditions:

{gpac_user_can_view}

Returns 'true' or 'false' for conditional visibility.

Hooks & Filters

Filters

gpac_role_mapping
Modify the role to grant program mapping programmatically:

add_filter('gpac_role_mapping', function($mapping) {
    $mapping['custom-role'] = 'custom-program';
    return $mapping;
});

gpac_filtered_post_types
Modify which post types are filtered:

add_filter('gpac_filtered_post_types', function($post_types) {
    $post_types[] = 'custom-post-type';
    return $post_types;
});

Troubleshooting

Users can't see content they should have access to

1. Check that the user's role is mapped to a grant program in Access Control
2. Verify the content is tagged with either:
   • The user's assigned grant program
   • The "all-grants" term
3. Check that the post type is in the Filtered Post Types list
4. Confirm the user is logged in

Users see content they shouldn't have access to

1. Check if the user's role is set to "All Content (No Restrictions)"
2. Verify the content isn't tagged with "all-grants"
3. Check if the post type is actually in the Filtered Post Types list
4. Clear any caching plugins

"No Access" page not working

Create a page with the slug no-access at /no-access/ to display to users who attempt to access restricted content.

Requirements

• WordPress 5.0 or higher
• PHP 7.4 or higher
• Custom taxonomy: grant-program
• User roles following the naming convention (for profile display features)

Changelog

5.3

• Updated universal access term from universal-grant to all-grants
• Improved admin interface descriptions
• Updated documentation

5.2

• Added Pie Calendar integration
• Added filter_piecal_query() method for event listings

5.1

• Added configurable filtered post types (moved from hardcoded)
• Added admin interface for selecting post types to filter

5.0

• Complete rewrite with improved architecture
• Added "All Content" option for unrestricted access
• Added top-level admin menu
• Added comprehensive filtering for Bricks, FacetWP, and archives
• Removed user profile fields (role management via Members plugin)

Support

For support, please contact KC Web Programmers.

Credits

Developed by KC Web Programmers for grant program content management and access control.