README

Sudoku puzzle plugin for TYPO3 v12, v13 and v14 (Extbase/Fluid rewrite of the legacy EXT:sudoku by Andreas Kastl).

Content element "Sudoku" with 10 difficulty levels, random or daily puzzle
Backend dashboard widget (optional, with EXT:dashboard)
Static maintenance page with a playable Sudoku for deployments

Full documentation (docs.typo3.org format): Documentation/. Render locally with docker run --rm -v $(pwd):/project ghcr.io/typo3-documentation/render-guides:latest --config=Documentation.

Requirements and installation


TYPO3	12.4, 13.4, 14.3 (`typo3/cms-core`, `cms-extbase`, `cms-fluid`)
Optional	`typo3/cms-dashboard` for the dashboard widget

composer require anubit/sudoku
vendor/bin/typo3 extension:setup -e sudoku

extension:setup creates the table tx_sudoku_puzzles and imports 500 puzzles (ext_tables_static+adt.sql). The puzzle records are read-only and admin-only.

Content element

Add the content element Sudoku (group "Plugins"). Settings (tab "Plugin"):

Setting	Values	Default
Puzzle source	`database` (imported puzzles) or `generated` (generated on the fly)	`database`
Mode	`random` (new puzzle on demand) or `daily` (same puzzle for everyone per day, fixed level)	`random`
Default level	1-10	1
Hide level selector	on/off (always hidden in daily mode)	off
Intro text	free text above the game	–

In the frontend the level selector and the buttons New puzzle, Start over (same puzzle, entries cleared) and Show solution sit in a panel behind an arrow toggle (collapsed by default, the state is remembered per browser). Playing:

digits 1-9 overwrite, arrow keys move, Backspace/Delete clears
conflicts in a row/column/box are marked, the active row/column/box and equal digits are highlighted, a counter shows the empty cells
a full board without conflicts is solved (the solution is not sent to the browser while playing)
buttons reload only the Sudoku block in the background; without JavaScript the board works as a plain form

The plugin is not cached (every request renders the player's current board).

TypoScript and templates

No TypoScript include is required. On TYPO3 v13/v14 the optional site set Sudoku (anubit/sudoku) only sets the default template paths. To override templates, add higher keys:

plugin.tx_sudoku.view {
    templateRootPaths.10 = EXT:my_sitepackage/Resources/Private/Extensions/Sudoku/Templates/
    partialRootPaths.10 = EXT:my_sitepackage/Resources/Private/Extensions/Sudoku/Partials/
}

Styling

All styles are scoped to .sudoku and use custom properties, e.g.:

.sudoku {
    --sudoku-max-width: 28em;        /* width of the game */
    --sudoku-cell-size: 42px;        /* board cell size */
    --sudoku-button-primary: #4a6cf0;
    --sudoku-button-danger: #e05d5d;
    --sudoku-info: #4a6cf0;          /* instructions box */
    --sudoku-card-bg: #fff;
}

See Resources/Public/Css/sudoku.css for the full list.

Dashboard widget

With EXT:dashboard installed, the backend dashboard offers a Sudoku widget (group "General"). It uses the same standalone game as the maintenance page: puzzles incl. solutions are embedded (levels 1-10, 3 per level, from the database), so playing needs no requests. Texts follow the backend user's language, text colours follow the backend light/dark mode.

Size medium x medium: board on the left, level, buttons and instructions on the right (one column when the widget is narrower than 600px).

Widget options (Configuration/Services.php, argument $options): levels (e.g. 1-5), count (puzzles per level), source (database or generated). Without EXT:dashboard the widget is not registered.

Maintenance page

The extension can generate a static maintenance page with a playable Sudoku. It is meant for times when TYPO3 itself is not available (deployment, composer install, database updates):

the page is generated in advance while TYPO3 works (sudoku:maintenance:build),
it is fully self-contained (CSS, JavaScript, puzzles incl. solutions, texts inline; no PHP, no database, no external requests),
the web server serves it with HTTP 503 while a flag file exists, so it works even when TYPO3 is broken.

1. Build the page

vendor/bin/typo3 sudoku:maintenance:build --lang=de

Writes <public>/maintenance.html. Options:

Option	Default
`--lang`, `-l`	`en`	Language of the texts (`en`, `de`, `nl`; from the extension's locallang files)
`--title`	`maintenance.title`	Heading
`--text`	`maintenance.text`	Text below the heading
`--logo`	–	Local file or `EXT:` path (embedded as data URI) or URL
`--levels`	`1-10`	Levels to include, e.g. `1-5` or `1,3,5`
`--count`, `-c`	`5`	Puzzles per level (1-50)
`--source`	`database`	`database` or `generated`; levels without database puzzles fall back to generated ones
`--output`, `-o`	`<public>/maintenance.html`	Target file

The page is a snapshot. Rebuild it after changing texts or the extension, ideally automatically at the end of every deployment, so an up-to-date page is ready for the next maintenance.

2. Switch maintenance on and off

vendor/bin/typo3 sudoku:maintenance:on    # creates <public>/maintenance.enable
vendor/bin/typo3 sudoku:maintenance:off   # removes it

sudoku:maintenance:on refuses to switch on while maintenance.html does not exist (--force/-f creates the flag anyway). If TYPO3 does not work any more (e.g. a failed deployment), remove the flag directly: rm public/maintenance.enable.

Example deployment (shell):

vendor/bin/typo3 sudoku:maintenance:on
# ... deploy, composer install, database updates ...
vendor/bin/typo3 sudoku:maintenance:off
vendor/bin/typo3 sudoku:maintenance:build --lang=de   # ready for next time

3. Web server rule (once per project)

The rule must run before PHP, so the page also appears when TYPO3 is broken.

Apache (top of public/.htaccess, above the TYPO3 rewrite rules; needs mod_rewrite, mod_headers optional):

# EXT:sudoku maintenance page: every request gets 503 + maintenance.html while maintenance.enable exists.
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{DOCUMENT_ROOT}/maintenance.enable -f
    RewriteCond %{REQUEST_URI} !=/maintenance.html
    # Optional: let your own IP through to test during maintenance
    # RewriteCond %{REMOTE_ADDR} !=203.0.113.10
    RewriteRule ^ - [R=503,L]
</IfModule>
ErrorDocument 503 /maintenance.html
<IfModule mod_headers.c>
    Header always set Retry-After "300" "expr=-f '%{DOCUMENT_ROOT}/maintenance.enable'"
    Header always set Cache-Control "no-store" "expr=-f '%{DOCUMENT_ROOT}/maintenance.enable'"
</IfModule>

nginx (inside the server block):

# EXT:sudoku maintenance page
error_page 503 @sudoku_maintenance;
location @sudoku_maintenance {
    add_header Retry-After 300 always;
    add_header Cache-Control "no-store" always;
    rewrite ^ /maintenance.html break;
}
if (-f $document_root/maintenance.enable) {
    return 503;
}

HTTP 503 with Retry-After tells search engines that the outage is temporary.

Languages

	English	German	Dutch
Frontend, maintenance page, widget (`locallang.xlf`)	✓	✓	✓
Backend: content element, settings, puzzle table (`locallang_db.xlf`)	✓	✓	–

Changelog

2.0.0 (2026-10-21)

Complete rewrite of the legacy extension 1.3.0 (TYPO3 4.5-6.2) for TYPO3 12.4, 13.4 and 14.3. The puzzle data is unchanged: the same 500 puzzles (50 per level) in the same table tx_sudoku_puzzles.

	1.3.0	2.0.0
TYPO3	4.5-6.2	12.4, 13.4, 14.3
Plugin	classic `pi1` plugin (`list_type` `sudoku_pi1`)	Extbase content element (`CType` `sudoku_game`)
Templates	uploaded HTML file with `###MARKERS###`	Fluid templates, overridable via TypoScript paths
Styling	`_CSS_DEFAULT_STYLE` in TypoScript	own stylesheet with CSS custom properties
Buttons	New, Check, Solve (full page reload)	New puzzle, Start over, Show solution (block reloads in the background)
Help while playing	errors only after "Check"	live: rule conflicts, highlighting, counter of empty cells
Puzzles	database	database or generated on the fly; random or puzzle of the day
Languages	EN, DE, NL	frontend EN, DE, NL; backend EN, DE

Added

Puzzle of the day (same puzzle for all visitors per day, fixed level)
Generated puzzles as alternative source to the database
"Start over" button: same puzzle, entries cleared
Live help: conflicts in rows/columns/boxes, highlighting of the active row/column/box and of equal digits, counter of empty cells, solved detection
Keyboard input (digits, arrow keys, Backspace/Delete)
Controls and instructions in a collapsible panel; icon buttons with tooltips; status messages with title and colour (instructions, solution, solved, note)
Accessibility: labels for every cell, status messages announced to screen readers, board caption
Works without JavaScript as a plain form
Backend dashboard widget (optional, with EXT:dashboard)
Static maintenance page with a playable Sudoku, CLI commands sudoku:maintenance:build, :on and :off, web server rules for Apache and nginx
Optional site set anubit/sudoku (TYPO3 13.4+)

Changed

Plugin settings: puzzle source, mode (random/daily), default level, hide level selector, intro text
Responsive layout; the game is limited to a compact width and centred

Removed

"Check" button (comparison with the solution); replaced by the live conflict marking, which checks the Sudoku rules while typing
Template file upload in the plugin settings (use Fluid template paths instead)

Upgrade from 1.x

Run vendor/bin/typo3 extension:setup -e sudoku; the puzzle table and data stay the same.
There is no automatic migration of content elements: replace existing "Sudoku" plugins (list_type sudoku_pi1) with the new content element "Sudoku".
Custom HTML templates and _CSS_DEFAULT_STYLE overrides have to be recreated as Fluid templates and CSS custom properties.

1.x (legacy, Andreas Kastl)

1.3.0 (2014-06-01): TYPO3 CMS 6.2 compatibility
1.2.0 (2013-08-06): TYPO3 CMS 6.x compatibility
1.1.1 (2013-03-11): dependency information for the TER cleanup
1.0.0 (2007-02-20): release 1.0.0, documentation completed; Dutch translation added on 2007-02-21
0.5.0 (2006-12-06): first beta uploaded to the TER
0.4.0 (2006-12-03): puzzles moved to the root page, table renamed to tx_sudoku_puzzles
0.3.0 (2006-11-30): pre-generated puzzles limited to 500 (50 per level)

anubit / sudoku

Package info

Security

Statistics