Content Analysis

The CTypes Widget provides comprehensive analysis of your website's content elements:

• Complete Overview: See all content element types (CTypes) used across your website
• Multi-language Statistics: View usage statistics for each configured language
• Smart Filtering: Show or hide deactivated content elements
• Export Functionality: Export detailed content data as CSV files
• Direct Navigation: Click on statistics to jump directly to content examples

TSConfig Integration

Advanced TSConfig management capabilities:

• Real-time Management: Enable or disable content element types directly from the dashboard
• Page-specific Configuration: Apply TSConfig rules to specific pages or globally
• Visual Feedback: Clear indication of activated and deactivated content elements
• Safety Features: Prevents accidental deactivation of content elements that are still in use

Interactive Entertainment

The Sudoku Widget adds engaging functionality to the backend:

• Full Sudoku Game: Complete implementation with puzzle generation and solving
• Progress Persistence: Game state is automatically saved per backend user
• Real-time Validation: Visual feedback for correct and incorrect entries
• Responsive Design: Optimized for both desktop and mobile use

Technical Excellence

Built with modern TYPO3 best practices:

• Multi-version Support: Compatible with TYPO3 v11.5, v12.4, and v13.4
• Modern Architecture: Dependency injection, services, and clean code structure
• Performance Optimized: Efficient caching and database queries
• Accessibility Compliant: Screen reader friendly and keyboard navigable
• Security First: Proper CSRF protection and input validation

Content Management Efficiency

DashBash helps TYPO3 administrators and developers:

• Optimize Content Structure: Identify unused content elements that can be safely removed
• Streamline Backend Interface: Disable unnecessary content element types to simplify the editor experience
• Analyze Content Usage: Understand how content is distributed across languages and pages
• Export Data: Generate reports for stakeholders or further analysis

Backend User Experience

• Quick Analytics: Get instant insights without navigating through multiple backend modules
• Entertainment Value: Provide a fun break for backend users with the Sudoku game
• Efficient Workflow: Direct links to content examples save time during content management

Developer Benefits

• TSConfig Management: Simplify the process of managing TYPO3 TSConfig rules
• Code Quality: Learn from well-structured, modern TYPO3 extension code
• Extensibility: Built with hooks and events for custom extensions

Method 1: Composer Installation (Recommended)

For Composer-based TYPO3 installations, use the following command:

composer require mrg/dashbash

This will:

• Download the extension and its dependencies
• Register the extension in your TYPO3 installation
• Make it available for activation

After installation, activate the extension:

# Via TYPO3 Console (if available)
vendor/bin/typo3 extension:activate dashbash

# Or via TYPO3 CLI
vendor/bin/typo3 extension:activate dashbash

Method 2: TYPO3 Extension Repository (TER)

For Classic Mode installations:

1. Access Extension Manager

   • Go to Admin Tools > Extensions in your TYPO3 backend
   • Make sure you're in "Get Extensions" mode

2. Search and Install

   • Search for "dashbash" in the extension repository
   • Click "Import and Install" next to the DashBash extension
   • The extension will be downloaded and made available

3. Activate Extension

   • Switch to "Installed Extensions" mode
   • Find "DashBash" in the list
   • Click the activation icon to enable the extension

Method 3: Manual Installation

For development or special deployment scenarios:

1. Download Extension

   • Download the extension from the TYPO3 Extension Repository
   • Or clone from the Git repository: git clone [repository-url]

2. Place Files

   • Extract/copy the extension files to typo3conf/ext/dashbash/
   • Ensure proper file permissions are set

3. Clear Cache

   # Clear all caches
   vendor/bin/typo3 cache:flush

   Copied!

4. Activate Extension

   • Go to Admin Tools > Extensions
   • Find "DashBash" and activate it

Basic Setup

No initial configuration is required. The extension works out-of-the-box with default settings.

Optional Configuration

For advanced features, you may configure:

TSConfig Filtering (Optional)

Enable advanced TSConfig management capabilities:

# In LocalConfiguration.php or AdditionalConfiguration.php
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['dashbash']['enableTsConfigFiltering'] = 1;

Development Logging (Development Only)

For development environments, debug logging is automatically enabled in Development/ddev context.

Common Issues

Extension Not Appearing in Dashboard

1. Clear all caches: vendor/bin/typo3 cache:flush
2. Verify dashboard system extension is active
3. Check browser console for JavaScript errors

Composer Installation Fails

1. Verify your composer.json allows the required TYPO3 versions
2. Update Composer: composer self-update
3. Try: composer require mrg/dashbash --no-scripts

Permission Errors (Manual Installation)

Ensure proper file permissions:

# Example for typical web server setup
sudo chown -R www-data:www-data typo3conf/ext/dashbash/
sudo chmod -R 755 typo3conf/ext/dashbash/

JavaScript/CSS Not Loading

1. Clear browser cache
2. Verify Resources/Public/ folder has proper permissions
3. Check TYPO3's resource handling configuration

Database Issues

DashBash uses TYPO3's built-in caching system. If you encounter cache-related issues:

# Flush specific cache
vendor/bin/typo3 cache:flush --group=system

# Or flush all caches
vendor/bin/typo3 cache:flush

Basic Configuration

The extension can be configured through the TYPO3 Extension Configuration interface:

1. Go to Admin Tools > Settings > Extension Configuration
2. Find "dashbash" in the list
3. Click the configure icon

Available Settings

Programmatic Configuration

You can also configure the extension programmatically in your site's configuration files:

In LocalConfiguration.php or AdditionalConfiguration.php:

<?php
// Enable TSConfig filtering
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['dashbash']['enableTsConfigFiltering'] = 1;

In ext_localconf.php of your site extension:

<?php
defined('TYPO3') or die();

// Configure DashBash
if (\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::isLoaded('dashbash')) {
    $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['dashbash']['enableTsConfigFiltering'] = 1;
}

Dashboard Widget Setup

After installation, widgets need to be added to dashboards:

1. Navigate to Dashboard

   • Go to Dashboard in the TYPO3 backend
   • Select an existing dashboard or create a new one

2. Add CTypes Widget

   • Click Add widget
   • Find "Number of content elements in the respective languages"
   • Click to add the widget to your dashboard

3. Add Sudoku Widget

   • Click Add widget
   • Find "An entertaining brain game for the TYPO3 backend"
   • Click to add the widget to your dashboard

Widget Positioning

Both widgets support different sizes:

CTypes Widget:

• Height: Large (recommended for full table visibility)
• Width: Large (recommended for all language columns)

Sudoku Widget:

• Height: Large (required for full game board)
• Width: Medium (optimal for game layout)

Understanding TSConfig Filtering

When enableTsConfigFiltering is activated, the CTypes Widget analyzes your page tree for TSConfig rules that affect content element visibility.

How it works:

1. Analysis: The extension scans all pages for relevant TSConfig configurations
2. Grouping: Similar configurations are grouped together to avoid duplication
3. Selection: You can select which TSConfig configuration to apply as a filter
4. Management: Enable/disable content elements with visual feedback

TSConfig Rule Examples

The extension recognizes these TSConfig patterns:

Hide specific content elements:

TCEFORM {
    tt_content {
        CType {
            removeItems := addToList(textmedia,bullets)
        }
    }
}

Hide specific plugins:

TCEFORM {
    tt_content {
        list_type {
            removeItems := addToList(news_pi1,powermail_pi1)
        }
    }
}

Keep only specific content elements:

TCEFORM {
    tt_content {
        CType {
            keepItems = text,textmedia,image
        }
    }
}

Page-specific Configuration

TSConfig rules can be applied at different levels:

Global (Root Page):

Affects all pages in the site tree

Page-specific:

Affects only the specific page and its subpages

Inherited:

Child pages inherit parent page TSConfig rules

Sudoku Game Caching

The Sudoku widget uses TYPO3's caching framework for game state persistence:

// Automatic cache configuration (no manual setup needed)
$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations']['dashbash_sudoku'] = [
    'frontend' => \TYPO3\CMS\Core\Cache\Frontend\VariableFrontend::class,
    'backend' => \TYPO3\CMS\Core\Cache\Backend\Typo3DatabaseBackend::class,
    'options' => [
        'defaultLifetime' => 365 * 24 * 3600, // 1 year
        'compression' => false
    ]
];

Cache Management

Clear Sudoku Cache:

# Clear specific cache
vendor/bin/typo3 cache:flush --group=dashbash

# Or via backend: Admin Tools > Maintenance > Flush TYPO3 and PHP Cache

Reset Individual Game:

Users can reset their Sudoku game using the "NEW" button in the widget.

Debug and Logging

For development environments, DashBash provides enhanced logging:

Automatic Development Setup:

In Development/ddev context, logging is automatically configured:

// Automatic 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' => Environment::getPublicPath() . '/fileadmin/logs/dashbash.txt',
        ],
    ],
];

Manual Development Logging:

<?php
// In AdditionalConfiguration.php for development
if (\TYPO3\CMS\Core\Core\Environment::getContext()->isDevelopment()) {
    $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/your/dashbash-debug.log',
            ],
        ],
    ];
}

Performance Optimization

Database Query Optimization:

The extension automatically optimizes database queries, but you can monitor performance:

-- Monitor tt_content queries in slow query log
-- Look for queries with 'dashbash' context comments

Memory Usage:

For sites with large amounts of content, consider:

• Implementing pagination in CTypes Widget
• Adjusting PHP memory limits if needed
• Using database query optimization

AJAX Route Security

All AJAX routes are automatically secured with TYPO3's built-in CSRF protection:

• dashbash_sudoku_update: Sudoku game state updates
• dashbash_sudoku_reset: Game reset functionality
• dashbash_ctype_csv_export: CSV export functionality
• dashbash_toggle_ctype: TSConfig content element toggling
• dashbash_session_data: Session data management

Backend User Permissions

DashBash respects TYPO3's backend user permissions:

• Dashboard Access: Users need dashboard module access
• TSConfig Management: Requires appropriate page permissions
• CSV Export: Respects content access permissions

Language Support

DashBash automatically detects and supports all configured site languages:

1. Site Configuration: Languages are read from your site configuration
2. Flag Display: Language flags are automatically displayed if configured
3. Content Analysis: Statistics are calculated per language

Example site configuration:

# config/sites/mysite/config.yaml
languages:
  -
    title: English
    enabled: true
    languageId: 0
    base: /
    locale: en_US.UTF-8
    flag: us
  -
    title: Deutsch
    enabled: true
    languageId: 1
    base: /de/
    locale: de_DE.UTF-8
    flag: de

Translation Management

The extension supports TYPO3's translation workflow:

• Backend Labels: All interface elements are translatable
• Multi-language Content: Analyzes content in all configured languages
• Export Localization: CSV exports include language-specific data

Complete Configuration Example

<?php
// Complete DashBash configuration example
// Place in LocalConfiguration.php or AdditionalConfiguration.php

// Enable all advanced features
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['dashbash']['enableTsConfigFiltering'] = 1;

// Development logging (only in development context)
if (\TYPO3\CMS\Core\Core\Environment::getContext()->isDevelopment()) {
    $GLOBALS['TYPO3_CONF_VARS']['LOG']['MRG']['Dashbash']['Widgets']['writerConfiguration'] = [
        \TYPO3\CMS\Core\Log\LogLevel::DEBUG => [
            \TYPO3\CMS\Core\Log\Writer\FileWriter::class => [
                'logFile' => \TYPO3\CMS\Core\Core\Environment::getPublicPath() . '/fileadmin/logs/dashbash.txt',
            ],
        ],
    ];
}

// Custom cache configuration (optional - defaults are usually sufficient)
$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations']['dashbash_sudoku']['options']['defaultLifetime'] = 7 * 24 * 3600; // 1 week

Site Package Integration

For site packages, you can include DashBash configuration:

<?php
// EXT:my_sitepackage/ext_localconf.php
defined('TYPO3') or die();

// Automatically enable DashBash features when available
if (\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::isLoaded('dashbash')) {
    $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['dashbash']['enableTsConfigFiltering'] = 1;
}

Adding Widgets to Dashboard

1. Navigate to Dashboard

   • Go to Dashboard in your TYPO3 backend main menu
   • Select an existing dashboard or create a new one by clicking Add Dashboard

2. Add Widgets

   • Click the Add widget button

   • You'll see two DashBash widgets available:

     • "Number of content elements in the respective languages" (CTypes Widget)
     • "An entertaining brain game for the TYPO3 backend" (Sudoku Widget)

3. Position and Size

   • Drag widgets to your preferred position
   • Resize widgets using the handles in the bottom-right corner

   • Recommended sizes:

     • CTypes Widget: Large height, Large width
     • Sudoku Widget: Large height, Medium width

Basic Usage

Understanding the Display

The widget shows a table with:

• Content Element Types: All CTypes configured in your TYPO3 installation
• Language Columns: One column for each configured site language (with flags)
• Usage Statistics: Number of elements of each type per language
• Direct Links: Click numbers to jump to content examples
• Actions Column: Management buttons (when TSConfig filtering is enabled)

Reading the Statistics

• Numbers: Show count of active, non-hidden content elements
• Empty cells: Indicate no content of that type in that language
• Links: Clicking a number opens the first active element of that type
• Plugin hierarchy: List-type plugins are shown indented under "list" CType

Navigation Features

Direct Content Access

1. Click any count number to navigate directly to an example of that content type
2. Links include anchor: Direct link to the specific content element (#c123)
3. Language context: Links respect the selected language context
4. Backend preview: Opens in the same or new tab based on your browser settings

Export Functionality

1. Individual Exports: Click the CSV icon next to any content type
2. Language-specific: Export data for specific language combinations

3. Detailed Data: Exported CSV includes:

   • Content element UID
   • Page UID
   • Content type
   • List type (for plugins)
   • Language UID
   • Element title/header

Export Data Format

uid,pid,ctype,list_type,sys_language_uid,title
123,45,textmedia,,0,"Welcome Text"
124,45,list,news_pi1,0,"News List"
125,46,textmedia,,1,"Willkommen Text"

Advanced Features (TSConfig Filtering)

When TSConfig filtering is enabled, additional management features become available:

Filter Selection

1. TSConfig Dropdown: Shows different TSConfig configurations found in your page tree
2. Page Context: Each option shows the page hierarchy where the configuration applies
3. "All" Option: Shows all content elements without filtering
4. Automatic Detection: Configurations are automatically discovered and grouped

Show/Hide Deactivated Elements

• Checkbox Control: Toggle visibility of deactivated content elements
• Visual Distinction: Deactivated elements shown with different styling
• State Persistence: Your selection is remembered across sessions

Content Element Management

Enable/Disable Content Elements

1. Action Buttons: Eye icon in the Actions column

2. Visual States:

   • Green button: Content element is enabled
   • Red button: Content element is disabled
   • Disabled button: Cannot be changed (safety restriction)

3. Safety Features:

   • Usage Check: Cannot disable content elements that are still in use
   • Plugin Dependencies: Cannot disable "list" while plugins are active
   • Confirmation: Visual feedback after changes
4. TSConfig Integration: Changes are written to page TSConfig automatically

Bulk Operations

• Page Selection: Apply changes to specific pages or globally ("all")
• Immediate Effect: Changes take effect immediately
• Cache Management: Relevant caches are cleared automatically

Statistics and Analysis

Understanding the Summary

At the bottom of the widget, you'll find summary statistics:

• Total Content Types: Number of different content element types available
• Used Content Types: Number of types that actually contain content
• Could be deactivated: Types with zero usage that can be safely disabled

Performance Insights

Use these statistics to:

• Optimize Backend UX: Remove unused content elements to simplify editor interface
• Identify Opportunities: Find content types that could be consolidated
• Monitor Usage: Track content distribution across languages
• Plan Cleanup: Identify unused elements for removal

Game Basics

Game Rules

Standard Sudoku rules apply:

• Fill a 9×9 grid with digits 1-9
• Each row must contain all digits 1-9
• Each column must contain all digits 1-9
• Each 3×3 sub-grid must contain all digits 1-9

Interface Elements

• Fixed Numbers: Pre-filled numbers in bold (cannot be changed)
• Input Fields: Clickable cells for your entries

• Validation Colors:

  • Green: Correct entry
  • Red: Incorrect entry
  • White/Default: Empty or not yet validated

Playing the Game

Making Moves

1. Click any empty cell to select it
2. Enter a number 1-9 using your keyboard or number pad
3. Real-time Validation: Cell color changes immediately
4. Correction: Click incorrect cells to change your entry
5. Empty Cells: Delete content to clear a cell

Game Features

• Auto-save: Progress is automatically saved as you play
• User-specific: Each backend user has their own game state
• Persistent: Game continues when you return later
• Responsive: Works on desktop and mobile devices

Completion

When you complete the puzzle:

• Celebration Message: Animated congratulations overlay
• Automatic Detection: System detects when puzzle is solved
• Continue Playing: Message disappears automatically
• New Game: Use the reset button to start fresh

Game Management

Starting New Games

1. Reset Button: Click the "NEW" button with the star icon
2. Immediate Reset: New puzzle generates instantly
3. Difficulty: Puzzles are generated with moderate difficulty (40 pre-filled cells)
4. Unique Solutions: Each puzzle has exactly one valid solution

Progress Management

• Session Persistence: Game state survives browser restarts
• User Isolation: Your progress doesn't affect other users
• Long-term Storage: Games are stored for up to one year
• Memory Efficiency: Only current game state is kept in memory

Common Issues and Solutions

CTypes Widget Issues

Widget shows "No data available"

1. Check if you have content elements in your database
2. Verify site language configuration is correct
3. Clear all caches: vendor/bin/typo3 cache:flush

CSV export downloads empty file

1. Check file permissions on /fileadmin/ directory
2. Verify PHP max_execution_time for large exports
3. Check browser popup blocker settings

TSConfig filtering not working

1. Verify enableTsConfigFiltering is set to 1 in extension configuration
2. Check that you have appropriate page permissions
3. Ensure TSConfig rules are properly formatted

Sudoku Widget Issues

Game doesn't save progress

1. Check database connectivity
2. Verify caching system is working: vendor/bin/typo3 cache:warmup
3. Clear browser cache and cookies

Numbers don't validate properly

1. Clear browser cache
2. Check browser console for JavaScript errors
3. Verify all JavaScript files are loading correctly

Reset button doesn't work

1. Check AJAX routes are properly configured
2. Verify CSRF tokens are working
3. Check network connectivity and server response

General Widget Issues

Widgets don't appear in dashboard

1. Verify extension is activated
2. Check that dashboard system extension is enabled
3. Clear all caches including browser cache
4. Check for PHP or JavaScript errors

Styling looks broken

1. Clear browser cache completely
2. Check if CSS files are loading (Network tab in browser dev tools)
3. Verify no conflicting styles from other extensions
4. Check for Content Security Policy restrictions

Content Management with CTypes Widget

Regular Analysis

• Weekly Reviews: Check content element usage regularly
• Before Major Changes: Analyze current state before restructuring
• After Extensions: Review impact of new extensions on content types
• Multi-language Sites: Pay attention to language-specific patterns

Cleanup Strategy

1. Identify Unused: Use statistics to find unused content elements
2. Check Dependencies: Verify no templates or TypoScript depend on unused types
3. Test Changes: Use TSConfig filtering to test impact before permanent changes
4. Document Changes: Keep record of disabled content elements

Team Collaboration

• Share Dashboards: Create team dashboards with relevant widgets
• Export Data: Provide CSV exports for content audits
• Training: Show editors how filtering affects their backend interface

Productive Sudoku Usage

Integration Tips

• Break Activity: Use during short breaks to refresh focus
• Team Building: Discuss puzzle strategies with colleagues
• Stress Relief: Engaging puzzle-solving can reduce work stress
• Cognitive Exercise: Keep your problem-solving skills sharp

Time Management

• Set Limits: Don't let games interfere with work productivity
• Use Timers: Set personal time limits for game sessions
• Strategic Breaks: Use games during natural workflow breaks

Performance Optimization

Large Sites

For TYPO3 installations with thousands of content elements:

• Database Optimization: Ensure proper indexing on tt_content table
• Regular Cleanup: Remove old, deleted content elements permanently
• Caching Strategy: Use appropriate cache lifetime settings
• Monitor Performance: Watch query execution times in development

Multi-language Sites

• Language Strategy: Consider which languages need active monitoring
• Export Scheduling: Large exports might be better scheduled during off-peak hours
• Progressive Loading: Consider implementing pagination for very large datasets