---
title: "AJAX version switcher"
manual: "Render guides"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3renderguides:ajaxversions"
source: "Developer/AjaxVersions.rst"
rendered: "2026-09-24T12:21:12+00:00"
---

# AJAX version switcher {#ajaxversions}

Rendered documentation provides a version switcher on top of the
navigation.

For documentation deployed on `docs.typo3.org` clicking on the version
switcher will perform an AJAX API request that lists all available
versions and languages for the current documentation.

For local rendering however, there are two issues that will lead to
the version switcher not working properly:

-   Rendered HTML files viewed via the `file:///` notation may not
    execute any JavaScript due to security considerations/configuration
    of your browser.
-   When viewing HTML files via `localhost` or a `.ddev.site` webserver,
    the AJAX call will fail due to [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
    (Cross-Origin Resource Sharing) security restrictions.

Developers of the `render-guides` project may need to simulate menu rendering though.

For them, navigation can be proxied and simulated.

## Making the proxy available {#ajaxversions-proxy}

A render that does not go to docs.typo3.org writes two proxies beside its
assets, `_resources/js/versions-proxy.php` and
`_resources/js/menu-proxy.php`, and points the version switch and the
"All documentation" menu at them. They are the same files that live in
`packages/typo3-docs-theme/assets/js/` in the repository of this project
(`<https://github.com/TYPO3-Documentation/render-guides>`).

The proxy passes the URL parameter `url` on to the actual `docs.typo3.org` API
endpoint, and returns its output locally, so that a page may read it: the
browser refuses to fetch it from the page itself, which is a foreign origin to
`docs.typo3.org`.

It is PHP, so the server showing the documentation has to run PHP -- the DDEV
integration of this project does, a server that only hands out files does not.
Without it the version switch and the menu stay empty, and the browser console
says so.

See [Configuring HTML data-attributes](https://docs.typo3.org/permalink/t3renderguides:ajaxversions-data-attributes) on how to fine-tune this.

## Details on how the version switcher is implemented {#details-on-how-the-version-switcher-is-implemented}

Local rendering is automatically detected via the absence of an environment variable
`TYPO3AZUREEDGEURIVERSION` (see [GitHub workflow: deploy-azure-assets](https://docs.typo3.org/permalink/t3renderguides:deploy-azure-assets)).

This allows a Twig function `isRenderedForDeployment` (defined in
`packages/typo3-docs-theme/src/Twig/TwigExtension.php` of this repository) to
conditionally generate output. The Twig template file
`packages/typo3-docs-theme/resources/template/structure/navigation/navigationHeader.html.twig`
makes use of that function to define some default HTML data-attributes for out-of-the-box
version witcher simulation, once the PHP proxy URL can be called without a 404 error.

The JavaScript is contained in `packages/typo3-docs-theme/assets/js/versions.js` and
contains the code for parsing the JSON response of the API, and sorting the keys appropriately.
More details can be found inside the code comments of that file.

When changing this JavaScript, the assets must be rebuilt (`ddev npm-build`) and
documentation must be rendered with the built assets (`make docs`).

The JavaScript file also contains some logic to set names for known published translations.
If a static name is not available, it is resolved to the ISO-code (like "de-de"). The
TYPO3 Documentation team can not easily access active server-side code to get an automatic
list of languages.

## Configuring HTML data-attributes {#ajaxversions-data-attributes}

The following data-attributes on the HTML element `<div id="toc-version">` are available:

-   `data-override-url-self` \- This is a full URL starting with `https://docs.typo3.org` which
    is used as the simulated page from which the version switching information is retrieved for.
    For example, `https://docs.typo3.org/m/typo3/tutorial-getting-started/12.4/en-us/Concepts/Index.html`.
-   `data-override-url-proxy` \- Points to the full URI of the [Making the proxy available](https://docs.typo3.org/permalink/t3renderguides:ajaxversions-proxy) PHP proxy.
    This is called due to CORS reasons. The default of this attribute is set to
    `https://render-guides.ddev.site/versions-proxy.php?url=`. Unless this file is manually
    copied to this URL, the proxy will return a 404 failure and inform about the non-working
    version switcher.

## Seeing the simulated output {#seeing-the-simulated-output}

Once the PHP proxy is in place, open the rendered documentation HTML file in your DDEV/webserver
environment (not using a `file:///` syntax, because then JavaScript may unavailable), for example

```
https://render-guides.ddev.site/Developer/AjaxVersions.html
```

You can then also use the browser's JavaScript console to manipulate the used URLs for
rendering, for example:

```
document.getElementById('toc-version').setAttribute('data-override-url-self', 'https://docs.typo3.org/other/t3docs/render-guides/main/en-us/Developer/InterlinkInventories.html');
```

This must be performed before actually clicking the version switcher link, because
the remote AJAX request is only performed once and then never again without reloading the page.