uiXpress
Role Editor

Operations Guide

Step-by-step guides for common role editor operations.

Creating a New Role

Step-by-Step Process

  1. Navigate to Role Editor
    • Go to uiXpress → Role Editor
    • Page loads with role list
  2. Open Create Modal
    • Click "New Role" button (top right)
    • Modal opens with form
  3. Enter Role Name
    • Type role name (e.g., "Manager")
    • Name is required
    • 1-100 characters allowed
  4. Review Slug (Optional)
    • Slug auto-generates from name
    • Edit if needed
    • Must be lowercase, alphanumeric, hyphens, underscores
    • Max 60 characters
  5. Create Role
    • Click "Create Role" button
    • Role created successfully
    • Navigate to role details
  6. Assign Capabilities
    • Select capabilities from categories
    • Use "Select All" for categories
    • Search for specific capabilities
    • Click "Save Changes"

Best Practices

  • Use Descriptive Names: Clear, descriptive role names
  • Follow Naming Conventions: Use consistent naming
  • Start with Minimal Capabilities: Add only what's needed
  • Test on Staging: Test role changes first
  • Document Purpose: Note role purpose

Editing Role Name

Step-by-Step Process

  1. Select Role
    • Click role in list
    • Role details open
  2. Enter Edit Mode
    • Click edit icon next to role name
    • Input field appears
    • Current name pre-filled
  3. Edit Name
    • Type new name
    • Name must be 1-100 characters
    • Trim whitespace automatically
  4. Save Changes
    • Press Enter or click Save
    • Name updates
    • List refreshes automatically
  5. Cancel (Optional)
    • Click Cancel or press Escape
    • Reverts to original name
    • Exits edit mode

Best Practices

  • Keep Names Clear: Use descriptive names
  • Avoid Special Characters: Keep names simple
  • Update Documentation: Update any documentation
  • Notify Users: Inform users of name changes

Assigning Capabilities

Step-by-Step Process

  1. Select Role
    • Click role in list
    • Role details open
  2. Navigate Capabilities
    • Scroll through categories
    • Expand categories to view capabilities
    • Use search to find specific capabilities
  3. Select Capabilities
    • Click checkbox to select
    • Use "Select All" for categories
    • Select individual capabilities
  4. Review Selection
    • Check selection count
    • Review progress bar
    • Verify selections
  5. Save Changes
    • Click "Save Changes" button
    • Confirm if Administrator role
    • Changes saved
    • Success notification

Capability Selection Strategies

Category-Based:

  • Select entire categories
  • Use "Select All" buttons
  • Review category contents
  • Deselect unnecessary capabilities

Individual Selection:

  • Select specific capabilities
  • Search for capabilities
  • Review each selection
  • Build custom permission set

Incremental Approach:

  • Start with minimal capabilities
  • Add capabilities as needed
  • Test functionality
  • Refine over time

Best Practices

  • Principle of Least Privilege: Only necessary capabilities
  • Test Functionality: Verify role works correctly
  • Document Changes: Note capability assignments
  • Review Regularly: Audit capabilities periodically
  • Use Categories: Organize by category

Removing Capabilities

Step-by-Step Process

  1. Select Role
    • Click role in list
    • Role details open
  2. Find Capabilities
    • Navigate to category
    • Use search if needed
    • Locate capability
  3. Deselect Capability
    • Click checkbox to deselect
    • Use "Deselect All" for categories
    • Remove individual capabilities
  4. Review Changes
    • Check selection count
    • Verify removals
    • Review impact
  5. Save Changes
    • Click "Save Changes"
    • Confirm if Administrator
    • Changes saved

Best Practices

  • Review Impact: Understand removal impact
  • Test Functionality: Verify role still works
  • Notify Users: Inform affected users
  • Document Changes: Note capability removals
  • Backup First: Backup before major changes

Deleting a Role

Step-by-Step Process

  1. Select Role
    • Click role in list
    • Role details open
  2. Check Deletability
    • Verify "Delete Role" button visible
    • Check user count (must be 0)
    • Ensure not default role
  3. Click Delete
    • Click "Delete Role" button
    • Confirmation dialog appears
  4. Confirm Deletion
    • Review role name
    • Read warning message
    • Click "Delete" to confirm
  5. Deletion Complete
    • Role deleted
    • List refreshes
    • Navigate to list view
    • Success notification

Pre-Deletion Checklist

  • ✅ No users assigned to role
  • ✅ Not a default WordPress role
  • ✅ Backup created
  • ✅ Users reassigned (if needed)
  • ✅ Documentation updated

Best Practices

  • Reassign Users First: Move users to other roles
  • Backup Before Deletion: Always backup first
  • Document Purpose: Note why role deleted
  • Verify Deletion: Confirm role removed
  • Update Documentation: Update any docs

Searching Roles

Step-by-Step Process

  1. Open Search
    • Click search bar
    • Focus on input
  2. Enter Search Term
    • Type role name or slug
    • Search is real-time
    • Case-insensitive
  3. View Results
    • Filtered list appears
    • Matching roles shown
    • Results count updates
  4. Clear Search (Optional)
    • Click clear button
    • Or delete search text
    • Full list restored

Search Tips

  • Use Partial Terms: Search by part of name
  • Search by Slug: Can search by slug too
  • Real-Time Results: Updates as you type
  • Case-Insensitive: No need for exact case

Searching Capabilities

Step-by-Step Process

  1. Open Capability Search
    • Click search bar in details view
    • Focus on input
  2. Enter Search Term
    • Type capability name
    • Search filters instantly
    • Case-insensitive
  3. View Results
    • Matching capabilities shown
    • Categories preserved
    • Empty categories hidden
  4. Select Capabilities
    • Select from filtered results
    • Search persists during selection
    • Clear search when done

Search Tips

  • Use Keywords: Search by capability keywords
  • Partial Matches: Partial terms work
  • Category Preservation: Categories maintained
  • Clear to Reset: Clear search to see all

Bulk Capability Operations

Select All in Category

  1. Expand Category
    • Click category header
    • Category expands
  2. Click "Select All"
    • Click "Select All" button
    • All capabilities selected
    • Button disabled
  3. Review Selection
    • Check selection count
    • Verify all selected
    • Save if satisfied

Deselect All in Category

  1. Expand Category
    • Click category header
    • Category expands
  2. Click "Deselect All"
    • Click "Deselect All" button
    • All capabilities deselected
    • Selection count updates
  3. Review Changes
    • Check selection count
    • Verify deselections
    • Save if satisfied

Managing Administrator Role

Special Considerations

Warning Banner:

  • Red warning always visible
  • Explains lockout risk
  • Prominent display
  • Cannot be dismissed

Confirmation Required:

  • Extra confirmation dialog
  • Must explicitly confirm
  • Cannot be bypassed
  • Clear warning message

Best Practices:

  • Test changes on staging first
  • Backup before changes
  • Document all changes
  • Have recovery plan
  • Avoid unnecessary changes

Safe Administrator Management

  1. Backup First
    • Full site backup
    • Database backup
    • File backup
  2. Test on Staging
    • Test all changes
    • Verify functionality
    • Confirm no lockout
  3. Make Changes
    • Make minimal changes
    • One change at a time
    • Test after each change
  4. Monitor Access
    • Verify admin access
    • Check functionality
    • Confirm no issues
  5. Document Changes
    • Record all changes
    • Note purpose
    • Update documentation

Troubleshooting

Common Issues

Role Not Found:

  • Verify role exists
  • Check role slug
  • Refresh page
  • Check permissions

Cannot Delete Role:

  • Check user count
  • Verify not default role
  • Reassign users first
  • Check permissions

Capabilities Not Saving:

  • Check permissions
  • Verify nonce
  • Check network
  • Refresh page

List Not Updating:

  • Refresh page
  • Check network
  • Verify API response
  • Clear cache

Error Messages

"Invalid role format":

  • Role slug invalid
  • Check format
  • Use valid characters

"Role name cannot be empty":

  • Name required
  • Enter name
  • Check length

"Cannot delete default WordPress roles":

  • Default role protected
  • Cannot delete
  • Use different role

"Cannot delete role. There are X user(s)":

  • Users assigned
  • Reassign users first
  • Then delete role

Best Practices Summary

Role Management

  • Use descriptive names
  • Follow naming conventions
  • Document role purpose
  • Review regularly
  • Keep minimal capabilities

Capability Management

  • Principle of least privilege
  • Test functionality
  • Document changes
  • Review periodically
  • Use categories

Security

  • Backup before changes
  • Test on staging
  • Monitor access
  • Document changes
  • Have recovery plan

User Communication

  • Notify users of changes
  • Explain new roles
  • Provide training
  • Update documentation
  • Gather feedback

Features

Detailed documentation of all role editor features and capabilities.

Security Documentation

Comprehensive security implementation details for the Role Editor feature.