Projects System Documentation

Projects Overview

The Projects system manages hierarchical project structures with support for parent-child relationships. Each project can have multiple sub-projects, and the system maintains data integrity through proper handling of user permissions and data validation.

Projects Controller

Key features in Comserv::Controller::Project:

• Project Creation: Handles form submissions with proper validation for:
  • Parent-child relationships (parent_id)
  • User authentication and username tracking
  • Required fields and data type validation
• Project Hierarchy: Manages up to 4 levels of sub-projects
• Project Listing: Displays projects in a card-based layout, sorted by name
• Error Handling: Provides detailed error messages and logging
• UI Configuration: Sets up the UI with:
  • CSS loading with cache-busting timestamps
  • Fluid container layout for better card display
  • Debug mode for troubleshooting
  • Template timestamp for forced reloading

Controller Code Example

# Add the projects and filter info to the stash
$c->stash(
    projects => $projects,
    role_filter => $role_filter,
    project_filter => $project_filter,
    priority_filter => $priority_filter,
    template => 'todo/project.tt',
    template_timestamp => time(), # Add a timestamp to force template reload
    additional_css => ['/static/css/components/project-cards.css?v=' . time()], # Add timestamp to force CSS reload
    use_fluid_container => 1, # Use fluid container for better card layout
    debug_mode => 1 # Enable debug mode to see template version
);

Projects Model

The database schema includes these key fields:

• id (Primary Key)
• name (Project name)
• parent_id (Optional, for sub-projects)
• sitename (Associated site)
• status (Project status)
• username_of_poster (Creator/owner)
• Various metadata fields (dates, descriptions, etc.)

Projects Templates

Current template structure:

• todo/project.tt: Main project listing with vertical card-based layout
  • Displays projects as collapsible vertical cards
  • Includes filter panel for project and priority filtering
  • Includes inline critical CSS to ensure proper rendering
  • Uses recursive macros to display hierarchical project structure
  • Implements JavaScript for collapsible functionality
• todo/add_project.tt: Project creation form
• todo/editproject.tt: Project editing interface
• todo/projectdetails.tt: Detailed project view
• todo/project_list.tt: Reusable component for project selection dropdowns

The template system uses Template Toolkit with the following features:

• Version tracking in PageVersion variable
• Debug mode support for troubleshooting
• Responsive design principles
• Role-based access control for admin functions
• Helper macros for complex UI components

Projects UI Components

The Projects system uses a vertical card-based UI for displaying projects:

Card Layout

• Card Header: Contains project name, priority badge, and collapse toggle
• Card Body: Displays project description, status badge, key details, and sub-projects
• Action Buttons: Details and Edit buttons within the card body
• Sub-Projects Container: Visually distinct area for sub-projects with left border and indentation

CSS Implementation

The card layout is implemented using a combination of:

• External CSS: /static/css/components/project-cards.css - Contains all card styling
• Inline Critical CSS: Embedded in the template to ensure proper rendering even if external CSS fails to load
• Bootstrap-Compatible Classes: Uses standard Bootstrap class names for compatibility
• Custom Classes: Additional classes for collapsible cards and sub-project containers

Responsive Design

• Vertical card layout that adapts to all screen sizes
• Collapsible cards to save vertical space
• Filter panel that adapts to mobile screens
• Fluid container for better use of screen space

Visual Indicators

• Priority Badges: Color-coded badges for High (red), Medium (yellow), Low (blue)
• Status Badges: New (blue), In Progress (primary), Completed (green)
• Icons: Font Awesome icons for improved visual cues
• Collapse Indicators: Chevron icons that rotate to indicate collapse state
• Sub-Project Indicators: Left border and indentation to show hierarchy

Projects Filtering

The Projects system includes a comprehensive filtering system:

Filter Panel

• Project Filter: Dropdown to select a specific project or sub-project
• Priority Filter: Dropdown to filter by priority level (High, Medium, Low)
• Apply Filters Button: Submits the filter form
• Clear Filters Button: Resets all filters

Filtering Logic

• Project Filtering: When a project is selected, only that project and its sub-projects are displayed
• Sub-Project Filtering: When a sub-project is selected, its parent project is displayed with only the selected sub-project
• Priority Filtering: Only projects with the selected priority are displayed
• Combined Filtering: Project and priority filters can be used together
• Hierarchical Awareness: Parent projects remain visible when their sub-projects match the filter

Implementation Details

• Template Macros: Helper macros determine if a project should be displayed based on filter criteria
• JavaScript: Auto-expands relevant projects when filtering
• Controller Support: The controller passes filter parameters to the template
• Query Parameters: Filters are maintained in the URL for bookmarking and sharing

Code Example: Filter Panel

<div class="filter-panel mb-4">
    <form id="projectFilterForm" class="form-inline" method="GET" action="/project/project">
        <div class="form-group mb-2">
            <label for="project_filter" class="mr-2">Project:</label>
            <select id="project_filter" name="project_id" class="form-control">
                <option value="">All Projects</option>
                
            </select>
        </div>
        
        <div class="form-group mb-2 ml-3">
            <label for="priority_filter" class="mr-2">Priority:</label>
            <select id="priority_filter" name="priority" class="form-control">
                <option value="">All Priorities</option>
                <option value="1" >High</option>
                <option value="2" >Medium</option>
                <option value="3" >Low</option>
            </select>
        </div>
        
        <button type="submit" class="btn btn-primary mb-2 ml-3">Apply Filters</button>
        <button type="button" id="clearFilters" class="btn btn-outline-secondary mb-2 ml-2">Clear Filters</button>
    </form>
</div>

Projects Workflow

1. Project Creation:
   • User fills out project form
   • System validates input and handles parent-child relationships
   • Project is created with proper user and site association
2. Project Management:
   • Projects can be viewed in hierarchical list
   • Admin users can edit project details
   • Sub-projects are managed within parent context

System Requirements and Limitations

• User must be authenticated for project creation
• Admin privileges required for editing projects
• Maximum of 4 levels in project hierarchy
• Project names must be unique within a site
• Browser must support CSS Flexbox for optimal card layout
• Font Awesome 5.x is required for icons

Active Project Hierarchies

Troubleshooting

CSS Display Issues

If projects are not displaying correctly as cards:

1. Verify that the CSS file is being loaded correctly (check browser developer tools)
2. Ensure the template is using the correct CSS classes
3. Check that the inline critical CSS is present in the template
4. Verify that the controller is setting use_fluid_container => 1
5. Check for JavaScript errors that might be affecting the layout

Collapsible Card Issues

If the collapsible functionality is not working:

1. Check browser console for JavaScript errors
2. Verify that the toggleCollapse function is defined in the template
3. Ensure that card IDs are unique and properly referenced in the onclick handlers
4. Check that the collapse icon is properly styled and transitions are working

Filtering Issues

If filtering is not working correctly:

1. Verify that the filter form is submitting to the correct URL
2. Check that the controller is correctly passing filter parameters to the template
3. Ensure that the is_parent_of_filtered_project macro is correctly implemented
4. Check the browser's network tab to confirm filter parameters are being sent
5. Verify that the NEXT statements in the template are correctly evaluating filter conditions

Debug Mode

Enable debug mode in the controller to see additional information:

$c->stash(debug_mode => 1);

This will display template version and CSS file information at the top of the page.

Common Issues

• Cards not collapsing/expanding: JavaScript errors or missing event handlers
• Filters not working: Form submission issues or incorrect template logic
• Sub-projects not displaying: Check the recursive macro implementation
• Parent projects not showing when filtering by sub-project: Issue with the is_parent_of_filtered_project macro
• Missing badges or icons: Font Awesome not loading correctly
• Auto-expand not working when filtering: JavaScript initialization issue

Logging

The Project controller logs important events to the application log:

$self->logging->log_with_details($c, 'debug', __FILE__, __LINE__, 'project', 'message');

Check logs/application.log for debugging information, especially filter parameters and project data structure.

JavaScript Debugging

For JavaScript-related issues, add console logging to the script:

console.log('Filter parameters:', {
    project: document.getElementById('project_filter').value,
    priority: document.getElementById('priority_filter').value
});

This can help identify issues with the collapsible functionality and filter handling.

Back to top