README

DashBash is a comprehensive TYPO3 extension that provides powerful dashboard widgets for content analysis and interactive entertainment within the TYPO3 backend.

🚀 Features

CTypes Widget

• Content Element Analysis: Complete overview of all content elements (CTypes) used across your website
• Multi-language Support: View content statistics for each configured language
• TSConfig Integration: Enable/disable content elements directly from the dashboard
• CSV Export: Export content element data for external analysis
• Interactive Filtering: Show/hide deactivated content elements
• Smart Statistics: Track which content elements are actually used and which can be safely deactivated

Sudoku Widget

• Interactive Sudoku Game: Fully functional Sudoku puzzle for TYPO3 backend entertainment
• Progress Persistence: Game state is saved per backend user
• Validation: Real-time validation with visual feedback for correct/incorrect entries
• Reset Functionality: Start new puzzles anytime
• Responsive Design: Works perfectly on desktop and mobile devices

Technical Features

• Multi-Version Compatibility: Supports TYPO3 v11.5, v12.4, and v13.4
• Modern Architecture: Built with dependency injection, services, and best practices
• Theme Support: Automatic dark/light theme adaptation
• Performance Optimized: Caching for game states and efficient database queries
• Accessibility: Screen reader friendly and keyboard navigable
• Security: Proper CSRF protection and input validation

📋 Requirements

• TYPO3: 11.5.0 - 13.4.99
• PHP: 7.4 or higher
• Extensions:
  • typo3/cms-core
  • typo3/cms-backend
  • typo3/cms-dashboard

📦 Installation

Via Composer (Recommended)

composer require mrg/dashbash

Via TYPO3 Extension Repository (TER)

1. Go to Admin Tools > Extensions in your TYPO3 backend
2. Search for "dashbash"
3. Install the extension
4. Activate the extension

Manual Installation

1. Download the extension from the TYPO3 Extension Repository
2. Upload to typo3conf/ext/dashbash/
3. Activate in Admin Tools > Extensions

⚙️ Configuration

Basic Setup

After installation, the widgets are automatically available in the dashboard:

1. Go to Dashboard in your TYPO3 backend
2. Click Add widget
3. Select from available DashBash widgets:
   • Content Elements Analysis (CTypes Widget)
   • Sudoku Game (Sudoku Widget)

Advanced Configuration

TSConfig Filtering (Optional)

Enable advanced TSConfig filtering in the Extension Configuration:

// In your site configuration or extension configuration
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['dashbash']['enableTsConfigFiltering'] = 1;

This enables:

• Page-specific content element filtering
• Bulk content element activation/deactivation
• TSConfig rule management from the dashboard

Development Context

For development environments, debug logging can be enabled:

// This is automatically enabled in Development/ddev context
$GLOBALS['TYPO3_CONF_VARS']['LOG']['MRG']['Dashbash']['Widgets']['writerConfiguration'] = [
    \TYPO3\CMS\Core\Log\LogLevel::DEBUG => [
        \TYPO3\CMS\Core\Log\Writer\FileWriter::class => [
            'logFile' => 'path/to/dashbash.log'
        ]
    ]
];

🎮 Usage

CTypes Widget

1. View Content Statistics: See how many content elements of each type are used across different languages
2. Export Data: Click the CSV export button next to any content type to download detailed data
3. Manage Content Elements:
   • Use the TSConfig filter dropdown to select specific page configurations
   • Toggle the "Show deactivated" checkbox to view disabled content elements
   • Click the eye button to activate/deactivate content element types
4. Navigate to Content: Click on the count numbers to jump directly to examples of that content type

Sudoku Widget

1. Play: Click on empty cells and enter numbers 1-9
2. Validation: Cells turn green for correct entries, red for incorrect ones
3. Completion: A congratulations message appears when the puzzle is solved
4. Reset: Click the "NEW" button to start a fresh puzzle
5. Auto-save: Your progress is automatically saved

🏗️ Architecture

Directory Structure

dashbash/
├── Classes/
│   ├── Widgets/           # Main widget implementations
│   ├── Service/           # Business logic services
│   ├── Controller/        # AJAX controllers
│   ├── ViewHelpers/       # Fluid view helpers
│   ├── Debug/             # Development utilities
│   └── Extern/            # External libraries (Sudoku generator)
├── Configuration/
│   ├── Services.yaml      # Dependency injection  
│   ├── Icons.php          # Icon registration
│   ├── JavaScriptModules.php # ES6 module configuration
│   └── Backend/AjaxRoutes.php # AJAX route definitions
├── Resources/
│   ├── Public/
│   │   ├── Css/           # Stylesheets with design system
│   │   ├── JavaScript/    # Frontend JavaScript (ES6 + v11 fallback)
│   │   └── Icons/         # SVG icons
│   └── Private/
│       ├── Templates/     # Fluid templates
│       ├── Language/      # Translation files
│       └── Layouts/       # Fluid layouts
└── Documentation/         # Complete documentation

Key Components

• CTypesWidget: Analyzes and manages content elements
• SudokuWidget: Provides interactive Sudoku gameplay
• TsConfigAnalysisService: Handles TSConfig filtering and analysis
• CTypeExportController: Manages CSV export functionality
• ArrayValueViewHelper: Custom Fluid ViewHelper for complex data access

🎨 Theming

DashBash includes a complete design system with:

• CSS Custom Properties: Easy theme customization
• Automatic Dark/Light Mode: Respects system preferences and manual settings
• Responsive Design: Mobile-first approach with breakpoints
• Accessibility: WCAG compliant color contrasts and focus indicators

Customization

Override CSS custom properties to match your theme:

:root {
  --color-primary: #your-brand-color;
  --color-success: #your-success-color;
  /* ... other properties */
}

🔧 Development

Local Development Setup

# Clone the repository
git clone https://github.com/your-username/dashbash.git
cd dashbash

# Install dependencies (if using ddev)
ddev composer install

Code Standards

• PSR-4 autoloading
• TYPO3 Coding Standards compliance
• PHPDoc documentation
• Type declarations where possible
• Modern PHP features (7.4+ syntax)

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following TYPO3 coding standards
4. Add tests if applicable
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📚 Documentation

Complete documentation is available in the Documentation/ folder and will be published on docs.typo3.org once approved.

🐛 Bug Reports & Feature Requests

Please use the GitHub Issues to report bugs or request features.

When reporting bugs, please include:

• TYPO3 version
• PHP version
• Extension version
• Steps to reproduce
• Expected vs actual behavior

📄 License

This extension is licensed under the GNU General Public License v2.0 or later.

👥 Author

Marko Röper-Grewe

• Email: marko.roeper-grewe@udg.de
• Company: MSQ / UDG
• Website: https://www.udg.de/

🙏 Acknowledgments

• TYPO3 Community for the excellent framework
• FontAwesome for the icons used in the extension
• The Sudoku puzzle generator is based on external algorithms

📈 Changelog

Version 13.0.0

• Improved public release
• Support for TYPO3 v11.5, v12.4 and v13.4
• CTypes Widget with full TSConfig integration
• Interactive Sudoku Widget
• Complete responsive design system
• Multi-language support
• CSV export functionality

Happy analyzing and playing! 🎯✨