.. include:: /Includes.rst.txt

.. _configuration:

=============
Configuration
=============

DashBash works out-of-the-box with sensible defaults, but offers several configuration options for advanced usage.

Extension Configuration
=======================

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
------------------

.. confval:: enableTsConfigFiltering

   :name: enableTsConfigFiltering
   :type: boolean
   :default: false

   Enables advanced TSConfig filtering functionality in the CTypes Widget.
   
   When enabled, you can:
   
   * Filter content elements by page-specific TSConfig rules
   * Enable/disable content element types directly from the dashboard
   * View different TSConfig configurations across your page tree

   **Example configuration:**

   .. code-block:: php

      $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['dashbash']['enableTsConfigFiltering'] = 1;

Programmatic Configuration
--------------------------

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

**In LocalConfiguration.php or AdditionalConfiguration.php:**

.. code-block:: php

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

**In ext_localconf.php of your site extension:**

.. code-block:: php

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

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

Widget Configuration
====================

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)

TSConfig Integration
====================

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:**

.. code-block:: typoscript

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

**Hide specific plugins:**

.. code-block:: typoscript

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

**Keep only specific content elements:**

.. code-block:: typoscript

   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

Caching Configuration
=====================

Sudoku Game Caching
--------------------

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

.. code-block:: php

   // 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:**

.. code-block:: bash

   # 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.

Development Configuration
=========================

Debug and Logging
------------------

For development environments, DashBash provides enhanced logging:

**Automatic Development Setup:**

In ``Development/ddev`` context, logging is automatically configured:

.. code-block:: php

   // 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:**

.. code-block:: php

   <?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:

.. code-block:: sql

   -- 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

Security Configuration
======================

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

Multi-Language Configuration
============================

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:**

.. code-block:: yaml

   # 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

Advanced Configuration Examples
===============================

Complete Configuration Example
-------------------------------

.. code-block:: php

   <?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:

.. code-block:: php

   <?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;
   }

Next Steps
==========

After configuration:

* :ref:`Learn how to use the widgets <usage>`
* :ref:`Explore advanced features <usage-advanced>`
* :ref:`Review troubleshooting guide <known-problems>`