UserEditorModal Documentation

Overview

The UserEditorModal component is a modal dialog used in the Vantage analytics and data platform for creating and editing user profiles within the application. It provides a user-friendly interface for inputting and managing personal and security information related to platform users. The component is designed to enhance user experience by ensuring that all necessary user details can be captured seamlessly.

Purpose

The primary purpose of the UserEditorModal is to facilitate the creation and updating of user accounts. It enables administrators to configure the following aspects of a user profile:

• Personal information (First name, Last name)
• Email address and password
• Assigned company
• User roles and active status

This component enhances usability by alerting users when vital information is missing and streamlining the process of managing user access and credentials.

Settings

The UserEditorModal component accepts several props that configure its behavior and display. Below is an exhaustive breakdown of each setting:

1. isOpen

• Input Type: Boolean
• Description: Determines whether the modal is currently displayed or not. When true, the modal is rendered; when false, it is hidden.
• Default Value: false

2. onClose

• Input Type: Function
• Description: A callback function that is invoked when the modal is requested to close. This allows parent components to handle modal visibility.
• Default Value: No default value; must be provided by the parent component.

3. user

• Input Type: Object (optional)
• Description: Represents the current user profile being edited. If provided, the modal pre-fills the form fields with the user's current information. If not provided, the fields remain empty for creating a new user.
• Default Value: null

4. onSave

• Input Type: Function
• Description: A callback function that is triggered when the user submits the form (either when creating a new user or saving changes). It receives the user input data as a parameter.
• Default Value: No default value; must be provided by the parent component.

5. clients

• Input Type: Array (optional)
• Description: A list of company clients to which the user can be assigned. It is used to populate the dropdown menu for selecting a company.
• Default Value: [] (an empty array)

6. roles

• Input Type: Array (optional)
• Description: A list of available roles that can be assigned to the user. This is used for managing user permissions and capabilities within the platform.
• Default Value: [] (an empty array)

Component Behavior

The UserEditorModal manages form data and responds to user interactions.

1. State Management:

   • The component maintains local state via the state management hook to store user input in the formData object.

2. Effect Hook:

   • The lifecycle management hook is employed to populate the form fields with existing user data when the user prop changes or a new user is created. Default values are set based on the presence of the user prop and the clients array.

3. Form Submission:

   • The handleSubmit function ensures that at least one role is assigned if it is a new user. On successful validation, it invokes the onSave callback with the current form data.

4. Toggling Active Status:

   • Users can toggle the active state of the account, affecting the UI to indicate whether the account is currently active or inactive.

Use Cases & Examples

Use Cases

1. Creating a New User Account: Admins can create new user profiles by providing necessary details such as name, email, password, company association, and desired roles.
2. Editing Existing User Accounts: Administrators can update existing user profiles, modifying information like email addresses or changing roles without needing to navigate away from the modal.
3. Setting User Account Status: The modal allows for easy toggling of user status (active/inactive), facilitating efficient user management and access control.

Example Configuration

Use Case: Creating a New Marketing User

In a scenario where an admin needs to create a new user for the marketing department, the following configuration might be applied:

<UserEditorModal
    isOpen={true}
    onClose={() => setModalOpen(false)}
    onSave={(userData) => handleUserSave(userData)}
    clients={[
        { id: 1, name: 'Marketing Company' },
        { id: 2, name: 'IT Solutions' }
    ]}
    roles={[
        { id: 1, name: 'Marketing Manager' },
        { id: 2, name: 'Marketing Associate' }
    ]}
/>

Form Data After Configuration

For a newly created marketing user, the expected formData upon form submission might be:

{
    "first_name": "Sarah",
    "last_name": "Conner",
    "email": "sarah.conner@example.com",
    "password": "securePassword123",
    "client_id": 1,
    "is_active": true,
    "roleIds": [1]
}

This configuration efficiently captures all necessary information to onboard a new user under the marketing department while associating them with their respective client. The onSave function will then handle this data appropriately, whether by updating a backend service or handling it within the application logic.