Administrative Operations

Relevant source files

The following files were used as context for generating this wiki page:

Purpose and Scope

This document outlines the administrative operations available in the osysHome-Users plugin. It covers how administrators can manage user accounts through the web interface, including adding, editing, and deleting users, setting passwords, and managing avatar images. For information about the plugin structure and initialization, see Plugin Structure, and for details about the user data models and forms, see User Data Models and Forms.

Overview of Administrative Operations

The osysHome-Users plugin provides a comprehensive set of administrative operations for user management. These operations are handled through the admin method in the Users class, which processes different operations based on the op query parameter.

flowchart TD
    A["Admin Interface"] -->|"op=add"| B["Add User"]
    A -->|"op=edit"| C["Edit User"]
    A -->|"op=delete"| D["Delete User"]
    A -->|"op=setPassword"| E["Set User Password"]
    A -->|"op=upload_image"| F["Upload User Avatar"]
    A -->|"no op (default)"| G["List All Users"]

    B -->|"form.validate_on_submit()"| H["addObject()"]
    C -->|"form.validate_on_submit()"| I["setProperty()"]
    D --> J["deleteObject()"]
    E -->|"passwords match"| K["set_password()"]
    F -->|"file upload"| L["save file & setProperty()"]
    G -->|"getObjectsByClass()"| M["render users.html"]

Sources: init.py:31-94

User Management Operations

Adding Users

Administrators can add new users through a form-based interface. The process involves:

Clicking the "Add user" button on the main users list page
Filling out the UserForm with username, role, home page, API key, and timezone
Submitting the form, which creates a new user object in the system

sequenceDiagram
    participant Admin as "Administrator"
    participant UI as "User Interface"
    participant Plugin as "Users Plugin"
    participant System as "System Core"
    
    Admin->>UI: Click "Add user" button
    UI->>Plugin: GET request with op=add
    Plugin->>UI: Display user form
    Admin->>UI: Fill form and submit
    UI->>Plugin: POST form data
    Plugin->>Plugin: Validate form data
    Plugin->>System: addObject(username, "Users")
    Plugin->>System: setProperty(role)
    Plugin->>System: setProperty(home_page)
    Plugin->>System: setProperty(apikey)
    Plugin->>System: setProperty(timezone)
    Plugin->>UI: Redirect to users list

The implementation handles the user creation through the addObject function, followed by setting various properties using setProperty method calls.

Sources: init.py:34-44, templates/users.html:6

Editing User Information

To edit an existing user:

Click the "Edit" button next to the user in the users list
Modify the pre-populated form with the user's current information
Submit the form to save the changes

The edit operation retrieves the user object, populates a form with the existing data, and then updates the user's properties when the form is submitted.

sequenceDiagram
    participant Admin as "Administrator"
    participant UI as "User Interface"
    participant Plugin as "Users Plugin"
    participant System as "System Core"
    
    Admin->>UI: Click "Edit" button for a user
    UI->>Plugin: GET request with op=edit&user=[username]
    Plugin->>System: getObject(username)
    System->>Plugin: Return user object
    Plugin->>UI: Display populated user form
    Admin->>UI: Modify data and submit
    UI->>Plugin: POST form data
    Plugin->>Plugin: Validate form data
    Plugin->>System: setProperty(role)
    Plugin->>System: setProperty(home_page)
    Plugin->>System: setProperty(apikey)
    Plugin->>System: setProperty(timezone)
    Plugin->>UI: Redirect to users list

Sources: init.py:45-56, templates/users.html:28

Deleting Users

Administrators can delete users by:

Clicking the "Delete" button next to the user in the users list
Confirming the deletion in the confirmation dialog

This operation is straightforward and uses the deleteObject function to remove the user from the system.

sequenceDiagram
    participant Admin as "Administrator"
    participant UI as "User Interface"
    participant Plugin as "Users Plugin"
    participant System as "System Core"
    
    Admin->>UI: Click "Delete" button for a user
    UI->>Admin: Display confirmation dialog
    Admin->>UI: Confirm deletion
    UI->>Plugin: GET request with op=delete&user=[username]
    Plugin->>System: deleteObject(username)
    Plugin->>UI: Redirect to users list

Sources: init.py:57-59, templates/users.html:30

Password Management

Setting a user's password is a separate operation with its own form:

Click the "Set password" button next to the user in the users list
Enter and confirm the new password in the password form
Submit the form to update the user's password

sequenceDiagram
    participant Admin as "Administrator"
    participant UI as "User Interface"
    participant Plugin as "Users Plugin"
    participant System as "System Core"
    
    Admin->>UI: Click "Set password" button
    UI->>Plugin: GET request with op=setPassword&user=[username]
    Plugin->>UI: Display password form
    Admin->>UI: Enter and confirm password
    UI->>Plugin: POST form data
    Plugin->>Plugin: Validate form and check passwords match
    Plugin->>System: getObject(username)
    System->>Plugin: Return user object
    Plugin->>Plugin: user.set_password(password)
    Plugin->>System: setProperty("password", hashed_password)
    Plugin->>UI: Redirect to home page

The password is hashed using the set_password method of the User class before being stored in the system.

Sources: init.py:60-69, templates/users.html:29

Avatar Image Management

Administrators can upload avatar images for users through an AJAX request:

Upload an image file
The file is saved to the server's filesystem in the avatars directory
The user's image property is updated with the URL to the saved image

sequenceDiagram
    participant Admin as "Administrator"
    participant UI as "User Interface"
    participant Plugin as "Users Plugin"
    participant Filesystem as "Server Filesystem"
    participant System as "System Core"
    
    Admin->>UI: Upload avatar image
    UI->>Plugin: POST request with op=upload_image, file and user
    Plugin->>Plugin: Validate file exists
    Plugin->>Filesystem: Create avatars directory if needed
    Plugin->>Filesystem: Save file to avatars directory
    Plugin->>System: setProperty(user + ".image", url_image)
    Plugin->>UI: Return JSON with image URL

The avatar image is stored in the private/avatars directory within the application's files directory, and the URL is stored as a property of the user.

Sources: init.py:70-87

Administrative Interface

The main administrative interface for user management is a table listing all users with options to perform the various operations:

classDiagram
    class "UsersTable" {
        +string Username
        +string Role
        +string HomePage
        +string LastLogin
        +Actions
    }
    
    class "Actions" {
        +Edit()
        +SetPassword()
        +Delete()
    }
    
    "UsersTable" --> "Actions"

The interface displays user information including:

Username with avatar
Role
Home page
Last login time
Action buttons for each user

At the top of the interface, there's an "Add user" button to create new users.

User Operations Flow

The following diagram illustrates how the different administrative operations fit together in the overall user management workflow:

stateDiagram-v2
    [*] --> UserList
    UserList --> AddUser: Click "Add user"
    UserList --> EditUser: Click "Edit"
    UserList --> SetPassword: Click "Set password"
    UserList --> DeleteUser: Click "Delete"
    
    AddUser --> ValidateAddForm: Submit
    ValidateAddForm --> CreateUser: Valid
    ValidateAddForm --> AddUser: Invalid
    CreateUser --> UserList: Redirect
    
    EditUser --> ValidateEditForm: Submit
    ValidateEditForm --> UpdateUser: Valid
    ValidateEditForm --> EditUser: Invalid
    UpdateUser --> UserList: Redirect
    
    SetPassword --> ValidatePasswordForm: Submit
    ValidatePasswordForm --> UpdatePassword: Valid
    ValidatePasswordForm --> SetPassword: Invalid
    UpdatePassword --> UserList: Redirect
    
    DeleteUser --> ConfirmDelete
    ConfirmDelete --> RemoveUser: Confirm
    ConfirmDelete --> UserList: Cancel
    RemoveUser --> UserList: Redirect

Sources: init.py:31-94, templates/users.html:1-36

Data Management

The plugin interacts with the underlying data system through several key functions:

Function	Purpose	Used In
`addObject`	Creates a new user object	Adding users
`getObject`	Retrieves a specific user by name	Editing users, setting passwords
`setProperty`	Updates a property of a user	All modification operations
`deleteObject`	Removes a user from the system	Deleting users
`getObjectsByClass`	Retrieves all users	Displaying the user list

Each operation is processed by the admin method in the Users class, which determines the action to take based on the op query parameter.

Sources: init.py:31-94

4_Administrative_Operations - Anisan/osysHome-Users GitHub Wiki

Administrative Operations

Purpose and Scope

Overview of Administrative Operations

User Management Operations

Adding Users

Editing User Information

Deleting Users

Password Management

Avatar Image Management

Administrative Interface

User Operations Flow

Data Management

⚠️ GitHub.com Fallback ⚠️

4_Administrative_Operations - Anisan/osysHome-Users GitHub Wiki

Administrative Operations

Purpose and Scope

Overview of Administrative Operations

User Management Operations

Adding Users

Editing User Information

Deleting Users

Password Management

Avatar Image Management

Administrative Interface

User Operations Flow

Data Management

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️