app.admin.routes

  1"""Admin routes for user and training module management.
  2
  3This file defines all `/admin/...` endpoints for creating, editing,
  4viewing and deleting users and training modules. All routes ensure that the
  5current user is authenticated and has the “admin” role.
  6"""
  7from datetime import datetime
  8
  9from flask import render_template, flash, redirect, url_for, request
 10from flask_login import current_user, login_required
 11
 12from app import app, db
 13from app.admin.forms import CreateUserForm, EditUserForm, CreateTrainingModuleForm
 14from app.models import (
 15    User, 
 16    Role, 
 17    Department, 
 18    TrainingModule, 
 19    Question, 
 20    Option, 
 21    OnboardingPath, 
 22    OnboardingStep
 23)
 24
 25
 26@app.route('/admin/register', methods = ['GET', 'POST'])
 27def register_user():
 28    """Register a new user.
 29
 30    Displays a form for creating a user, validates input, determines the
 31    appropriate onboarding path based on department, sets the password,
 32    and commits the new User record to the database.
 33
 34    Args:
 35        None (form data submitted via POST).
 36
 37    Returns:
 38        - Redirects to logout if the user is not an admin. 
 39        - Re-renders the registration form on GET or validation failure.
 40        - Redirects to manage_users on successful creation (with a flash
 41        message).
 42    """
 43    if not current_user.is_authenticated or current_user.role.role_name != 'admin':
 44        return redirect(url_for('logout'))
 45
 46    form = CreateUserForm()
 47
 48    form.role.choices = [(0, 'Select Role')] + [
 49        (role.id, role.role_name) for role in Role.query.all()
 50    ]
 51    form.department.choices = [(0, 'Select Department')] + [
 52        (dept.id, dept.department_name) for dept in Department.query.all()
 53    ]
 54
 55    manager_role = Role.query.filter_by(role_name='manager').first()
 56    manager_choices = [(0, 'None')]
 57    if manager_role:
 58        manager_choices += [
 59            (u.id, f"{u.first_name.title()} {u.surname.title()}")
 60            for u in User.query.filter_by(role_id=manager_role.id)
 61        ]
 62    form.manager.choices = manager_choices
 63
 64    if form.validate_on_submit():
 65        department_id = int(form.department.data)
 66
 67        if Department.query.filter_by(
 68            id=department_id, 
 69            department_name = "office",
 70        ).first():
 71            onboarding_path = OnboardingPath.query.filter_by(
 72                path_name = "office",
 73            ).first()
 74        else:
 75            onboarding_path = OnboardingPath.query.filter_by(   
 76                path_name = "operational",
 77            ).first()
 78       
 79        user = User(
 80            first_name = form.firstName.data,
 81            surname = form.surname.data,
 82            username = form.username.data,
 83            role_id = int(form.role.data),
 84            is_onboarding = (form.is_onboarding.data == 'yes'),
 85            manager_id = int(form.manager.data) if form.manager.data else None,
 86            department_id = int(form.department.data),
 87            onboarding_path_id = onboarding_path.id if onboarding_path else None,
 88            dateStarted = datetime.now(),
 89            job_title = form.job_title.data
 90        )
 91
 92        user.set_password(form.password.data)
 93        db.session.add(user)
 94        db.session.commit()
 95        flash(
 96            f'User {user.first_name} {user.surname} '
 97            'has been successfully registered!'
 98        )
 99        return redirect(url_for('manage_users'))
100    
101    return render_template(
102        'admin/createUser.html', 
103        title='Register User', 
104        form=form,
105    )
106
107
108@app.route('/admin/dashboard')
109@login_required
110def admin_dashboard():
111    """Display the admin dashboard.
112
113    Returns:
114        - Rendered admin dashboard template.
115        - Redirects to logout if the user is not an admin.
116    """
117    if current_user.role.role_name!= "admin":
118        return redirect(url_for('logout'))
119    
120    return render_template(
121        'admin/dashboard.html', 
122        title='Admin Dashboard',
123    )
124
125
126@app.route('/admin/manage_users', methods = ['GET'])
127@login_required
128def manage_users():
129    """Display all users in the system.
130
131    Returns:
132        - Rendered template with a list of all users.
133        - Redirects to the admin dashboard with a flash message if an error 
134        occurs.
135        - Redirects to logout if the user is not an admin.
136    """
137    if current_user.role.role_name != "admin":
138        return redirect(url_for('logout'))
139     
140    try:
141        users = User.query.all()
142        return render_template(
143            'admin/manageUsers.html',
144            title='Manage Users',
145            users=users,
146        )
147    except Exception as e:
148        print('Error: ' + str(e))
149        flash("An error occured contact support.")
150        return redirect(url_for('admin_dashboard'))
151
152
153@app.route('/admin/view_user/<int:user_id>', methods=['GET'])
154@login_required
155def view_user(user_id):
156    """View details of a specific user.
157
158    Args:
159        user_id (int): ID of the user to view.
160    
161    Returns:
162        - Rendered template with user details.
163        - Redirects to logout if the user is not an admin.
164    """
165    if current_user.role.role_name != "admin":
166        return redirect(url_for('logout'))
167
168    user = User.query.get_or_404(user_id)
169
170    return render_template(
171        'admin/viewUser.html', 
172        title='View User', 
173        user=user,
174    )
175
176
177@app.route('/admin/edit_user/<int:user_id>', methods = ['GET', 'POST'])
178@login_required
179def edit_user(user_id):
180    """Edit details of a specific user.
181
182    Displays a form pre-populated with the user's current details.
183    Validates the form on submission, updating the user record in the database.
184
185    Details:
186        - If `password` is left blank, the existing hashed password is unchanged.
187        - The `manager` dropdown uses 0 to represent “None” (no manager).
188
189    Args:
190        user_id (int): ID of the user to edit.
191
192    Returns:
193        - Rendered template with the edit user form.
194        - Redirects to logout if the user is not an admin.
195        - Redirects to manage_users on successful update with a flash message.
196    """
197    if current_user.role.role_name != "admin":
198        return redirect(url_for('logout'))
199    
200    user = User.query.get_or_404(user_id)
201    form = EditUserForm(obj=user)
202    form.user_id = user.id
203
204    form.role.choices = [
205        (role.id, role.role_name) for role in Role.query.all()
206]
207    form.department.choices = [
208        (dept.id, dept.department_name) for dept in Department.query.all()
209    ]
210
211    manager_role = Role.query.filter_by(role_name='manager').first()
212    manager_choices = [(0, 'None')]
213    if manager_role:
214        manager_choices += [
215            (u.id, f"{u.first_name.title()} {u.surname.title()}")
216            for u in User.query.filter_by(role_id=manager_role.id)
217        ]
218    form.manager.choices = manager_choices
219  
220    if request.method == 'GET':
221        form.role.data = user.role_id
222        form.department.data = user.department_id
223        form.manager.data = user.manager_id or 0   
224        form.is_onboarding.data = 'yes' if user.is_onboarding else 'no'
225
226    if form.validate_on_submit():
227        user.first_name = form.first_name.data
228        user.surname = form.surname.data
229        user.username = form.username.data
230        user.role_id = int(form.role.data)
231        user.is_onboarding = (form.is_onboarding.data == 'yes')
232        user.manager_id = int(form.manager.data) if form.manager.data else None
233        user.department_id = int(form.department.data)
234        user.job_title = form.job_title.data
235
236        if form.password.data:
237            user.set_password(form.password.data)
238
239        if form.dateStarted.data:
240            user.dateStarted = form.dateStarted.data
241
242        db.session.commit()
243
244        flash(
245            f'User {user.first_name} {user.surname} '
246            'user details have been updated')
247        return redirect(url_for('manage_users'))
248    
249    return render_template(
250        'admin/editUser.html', 
251        title='Edit User', 
252        form=form, 
253        user=user,
254    )
255
256
257@app.route('/admin/delete_user/<int:user_id>', methods=['POST'])
258@login_required
259def delete_user(user_id):
260    """Delete a user from the system.
261
262    Details:
263        - Users are prevented from deleting their own account.
264
265    Args:
266        user_id (int): ID of the user to delete.
267
268    Raises:
269        404 error if the user does not exist.
270
271    Returns:
272        - Redirects to manage_users on successful deletion with a flash 
273        message.
274        - Redirects to manage_users with a flash message if the user tries
275        to delete their own account.
276        - Redirects to logout if the user is not an admin.
277    """
278    if current_user.role.role_name != 'admin':
279        return redirect(url_for('logout'))
280        
281    user = User.query.get_or_404(user_id)
282
283    if user.id == current_user.id:
284        flash("You cannot delete your own account.")
285        return redirect(url_for('manage_users'))
286
287    db.session.delete(user)
288    db.session.commit()
289    flash(f"User {user.first_name} {user.surname} has been deleted.")
290
291    return redirect(url_for('manage_users'))
292
293
294@app.route('/admin/create_training_module', methods = ['GET', 'POST'])
295@login_required
296def create_training_module():
297    """Create a new training module.
298
299    This route allows an admin to create a new training module, including
300    questions and options. It handles form submission, validation, and
301    associates the module with onboarding pathways. 
302
303    Details:
304        - A POST with `add_question` in the form will append an extra
305          question entry and re-render the form without saving.
306
307    Args:
308        None (form data submitted via POST).
309    
310    Returns:
311        - Redirects to manage_training_modules with a flash message on 
312        successful creation.
313        - Re-renders the “create” template if fields are invalid or when 
314        dynamically adding a question.
315        - Redirects to logout if the user is not an admin.
316    """
317    if current_user.role.role_name != "admin":
318        return redirect(url_for('logout'))
319
320    form = CreateTrainingModuleForm()
321    form.pathways.choices = [
322        (path.id, path.path_name) 
323        for path in OnboardingPath.query.all()
324    ]
325
326    if request.method == 'POST' and 'add_question' in request.form:
327        form.questions.append_entry()
328        return render_template(
329            'admin/create_training_module.html', 
330            title = 'Create Training Module', 
331            form = form
332        )
333
334    if form.validate_on_submit():
335        try:
336            training_module = TrainingModule(
337                module_title = form.module_title.data,
338                module_description = form.module_description.data,
339                module_instructions = form.module_instructions.data,
340                video_url = form.video_url.data or None
341            )
342            db.session.add(training_module)
343            db.session.flush()
344
345            for pathway_id in form.pathways.data:
346                pathway = OnboardingPath.query.get(pathway_id)
347                if pathway:
348                    onboarding_step = OnboardingStep(
349                        step_name = training_module.module_title,
350                        path = pathway,
351                        training_module = training_module
352                    )
353                    db.session.add(onboarding_step) 
354            
355            if not form.questions.data:
356                flash("You must add at least one question.")
357                db.session.rollback()
358                return redirect(url_for('create_training_module'))
359            
360            for question_form in form.questions:
361                question = Question(
362                    question_text = question_form.question_text.data,
363                    training_module = training_module
364                )
365                db.session.add(question)
366                db.session.flush()
367                for option_form in (
368                    question_form.option1, 
369                    question_form.option2, 
370                    question_form.option3, 
371                    question_form.option4,
372                ):
373                    option = Option(
374                        option_text = option_form.option_text.data,
375                        is_correct = option_form.is_correct.data,
376                        question = question,
377                    )
378                    db.session.add(option)
379
380            db.session.commit()  
381            flash(
382                f'Training module "{training_module.module_title}" has been '
383                'successfully created!')
384            return redirect(url_for('manage_training_modules'))
385    
386        except Exception as e:
387            db.session.rollback()
388            print(f'Error: {str(e)}')
389            flash("An error occurred, please contact support.")
390            return redirect('admin/create_training_module.html', title='Create Training Module', form=form)
391
392    return render_template('admin/create_training_module.html', title='Create Training Module', form=form)
393
394    
395
396@app.route('/admin/manage_training_modules', methods = ['GET'])
397@login_required
398def manage_training_modules():
399    """Display all active training modules.
400
401    Returns:
402        - Rendered template with a list of all active training modules.
403        - Redirects to logout if the user is not an admin.
404    """
405    if current_user.role.role_name != "admin":
406        return redirect(url_for('logout'))
407    
408    modules = TrainingModule.query.filter_by(active=True).all()
409    
410    return render_template(
411        'admin/manage_training_modules.html',
412        title = 'Manage Training Modules',
413        modules = modules
414    )
415
416
417@app.route('/admin/details_training_module/<int:module_id>', methods = ['GET'])
418@login_required
419def details_training_module(module_id):
420    """Display details of a specific training module.
421
422    Args:
423        module_id (int): ID of the training module to view.
424
425    Raises:
426        404 error if the module does not exist.
427
428    Returns:
429        - Rendered template with training module details and associated 
430        questions.
431        - Redirects to logout if the user is not an admin.
432    """
433    if current_user.role.role_name != "admin":
434        return redirect(url_for('logout'))
435    
436    module = TrainingModule.query.get_or_404(module_id)
437    
438    questions = Question.query.filter_by(training_module_id=module_id).all()
439    
440    return render_template(
441        'admin/details_training_module.html', 
442        title=f'{module.module_title} Details',
443        module=module,
444        questions=questions
445    )
446
447
448@app.route('/admin/edit_training_module/<int:module_id>', methods = ['GET', 'POST'])
449@login_required
450def edit_training_module(module_id):
451    """Edit an existing training module.
452
453    This route allows an admin to edit the details of a training module,
454    including its title, description, instructions, video URL, and associated
455    questions and options. It also allows the admin to assign the module to
456    specific onboarding pathways.
457
458    Details:
459        - OnboardingStep entries are cleared and re-created based on the form
460          submission.
461        - Questions and options are updated based on the form data.
462
463    Args:
464        module_id (int): ID of the training module to edit.
465    
466    Raises:
467        404 error if the module does not exist.
468
469    Returns:
470        - Rendered template with the edit form pre-populated with the
471        module's current details.
472        - Redirects to manage_training_modules on successful update with a
473        flash message.
474        - Re-renders the edit form if validation fails or on GET request.
475        - Redirects to logout if the user is not an admin.
476    """
477    if current_user.role.role_name != "admin":
478        return redirect(url_for('logout'))
479    
480    module = TrainingModule.query.get_or_404(module_id)
481
482    form = CreateTrainingModuleForm(obj=module)
483    form.pathways.choices = [
484        (path.id, path.path_name) for path in OnboardingPath.query.all()
485    ]
486
487    if request.method == 'GET':
488        form.questions.entries.clear()
489        for question in module.questions:
490            question_form = form.questions.append_entry()
491            question_form.question_text.data = question.question_text
492            for i, option in enumerate(question.options):
493                sub = getattr(question_form, f'option{i+1}')
494                sub.option_text.data = option.option_text
495                sub.is_correct.data  = option.is_correct
496
497        form.pathways.data = [
498            step.onboarding_path_id 
499            for step in module.onboarding_steps
500        ]
501
502    if form.validate_on_submit():
503        module.module_title = form.module_title.data
504        module.module_description = form.module_description.data
505        module.module_instructions = form.module_instructions.data
506        module.video_url = form.video_url.data or None
507
508        OnboardingStep.query.filter_by(training_module_id = module.id).delete()
509        for path_id in form.pathways.data:
510            path = OnboardingPath.query.get(path_id)
511            db.session.add(OnboardingStep(
512                step_name=module.module_title,
513                path=path,
514                training_module=module
515            ))
516        for i in range(len(module.questions)):
517            question_obj = module.questions[i]
518            question_form = form.questions[i]
519
520            question_obj.question_text = question_form.question_text.data
521
522            for j, option_obj in enumerate(question_obj.options):
523                option = getattr(question_form, f'option{j+1}')
524                option_obj.option_text = option.option_text.data
525                option_obj.is_correct  = option.is_correct.data
526
527        db.session.commit()
528        flash(f'"{module.module_title}" has been updated.')        
529        return redirect(url_for('manage_training_modules'))
530    elif request.method == 'POST':
531        flash('Please check form for errors.')
532
533    return render_template(
534        'admin/edit_training_module.html',            
535        title=f'Edit Module: {module.module_title}',
536        form=form,
537        module=module
538    )
539
540
541@app.route('/admin/delete_training_module/<int:module_id>', methods=['POST'])
542@login_required
543def delete_training_module(module_id):
544    """Deactivate a training module. 
545
546    This marks the module as inactive so it no longer appears in listings.
547    It does not delete the record from the database.
548
549    Args:
550        module_id (int): ID of the training module to be deleted.
551        
552    Raises:
553        404 error if the module does not exist.
554
555    Returns:
556        - Redirect to the training module management page with a success message.
557        - Redirects to logout if the user is not an admin.
558    """
559    if current_user.role.role_name != 'admin':
560        return redirect(url_for('logout'))
561
562    module = TrainingModule.query.get_or_404(module_id)
563    module.active = False
564
565    try:
566        db.session.commit()
567        flash(f'Module "{module.module_title}" has been deleted.')
568    except Exception as e:
569        db.session.rollback()
570        print(f'Failed to deactivate module {module_id}: {e}')
571        flash('An error occurred while deleting the module. Contact support.')
572
573    return redirect(url_for('manage_training_modules'))