Headless allows you to render JSON from TYPO3 content. You can customize output by changing types, names and nesting of fields.
This extension provides backend part (JSON API) for TYPO3 PWA solution. Second part is a JavaScript application nuxt-typo3 which consumes JSON API and renders the content using Vue.js and Nuxt. See frontend documentation here: https://typo3-headless.github.io/nuxt-typo3/
If you have any questions just drop a line in #initiative-headless-pwa Slack channel.
- JSON API for content elements
- JSON API for page and meta data
- JSON API for navigation, layouts
- taking into account all language and translation configuration (e.g. fallback)
- easily extendable with custom fields or custom content elements
- custom data processors directly for headless usage
- support for EXT:form
- support for EXT:felogin
- support for EXT:redirects
- support for EXT:seo
- [BETA] backend module for simulating page preview (with specific page type, lang, usergroup) see headless_dev_tools
- headless support for EXT:news headless_news
- headless support for EXT:solr headless_solr
- headless support for EXT:powermail headless_powermail
- headless support for EXT:gridelements headless_gridelements
- small tools/tweaks for local headless development headless_dev_tools
- headless support for EXT:container headless-container-support and headless_container
| EXT:headless version | TYPO3 support | PHP support | Status |
|---|---|---|---|
>= 4.0 |
12 |
>= 8.1 |
Active development & support |
>= 3.0 |
11 |
>= 7.4, <= 8.2 |
Active support |
>= 2.0 |
9, 10 |
>= 7.2, <=7.4 |
Critical bugfixes only |
If you want to take a look at working demo including frontend, backend and demo data, use our DDEV based demo project here: https://github.com/TYPO3-Initiatives/pwa-demo
Install extension using composer
composer require friendsoftypo3/headless
Then, you should include extension typoscript template, and you are ready to go. Also, please remember to don't use fluid styled content on the same page tree together with ext:headless.
In headless extension we implemented new JSON Content Object, which allows you to specify what fields you want to output, and how they will look. First, let's take a look at simple example
lib.page = JSON
lib.page {
fields {
header = TEXT
header {
field = header
}
}
}
Output
{
"header" : "headerFieldValue"
}
in addition, keyword fields allow you to nest multiple times fields in json, e.g.
lib.page = JSON
lib.page {
fields {
data {
fields {
foo = TEXT
foo {
field = bar
}
foo1 = TEXT
foo1 {
field = bar1
}
}
}
}
}
Output
{
"data": [
{
"foo": "bar",
"foo1": "bar1"
}
]
}
We introduce new simple content objects to improve JSON API response for frontend developers. We can set correct property types, so frontend does not have to deal with string values for fields with numeric values or field that should be true/false.
lib.page = JSON
lib.page {
fields {
data {
fields {
foo = INT
foo {
# db value of foo_field = 1
field = foo_field
}
bar = BOOL
bar {
# db value of bar_field = 0
field = bar_field
}
}
}
}
}
Output
{
"data": [
{
"foo": 1,
"bar": false
}
]
}
You can override every field in output using typoscript. This extension allows you to use standard typoscript objects such as TEXT, COA, CASE.
In headless v3.0 we introduce a new, smaller, faster and more flat page response. If you want to keep compatibility with your frontend application, you can load a deprecated typoscript template for version 2.x and keep the old structure of the response running.
since version 3.x & under active maintenance
You can use Data Processors just like in FLUIDTEMPLATE Content Object, e.g.
lib.languages = JSON
lib.languages {
dataProcessing {
10 = TYPO3\CMS\Frontend\DataProcessing\LanguageMenuProcessor
10 {
languages = auto
as = languages
}
}
}
We provide multiple data processors for headless rendering purposes.
Used for fetching records from the database.
This processor should be used to process files (standard or media files).
Also, it allows you to process images. See docs chapter: Images for details.
Should be used along with FilesProcessor (chained). Used for processing mutliple media files.
Used for navigation. Works just like standard menu processor.
Used for processing flexforms.
Render your all headless sites configuration for your frontend application.
- Not Enabled: Headless mode is deactivated.
- Mixed Mode: Fluid and headless operate concurrently.
- Fully Headless Mode: Headless mode is fully activated.
To set up headless mode, utilize the site configuration flag as shown below:
'headless': 0|1|2While the legacy flag (true|false) is still recognized, transitioning to the integer notation is recommended.
- 0 (formerly: false) = headless mode is deactivated for the site within the TYPO3 instance.
- 1 (formerly: true) = headless mode is fully activated for the site within the TYPO3 instance.
- 2 = mixed mode headless is activated (both fluid & json API are accessible within a single site in the TYPO3 instance).
Options 0 (formerly: false) or 1 (formerly: true) inform the extension to either fully disable or enable headless mode for a particular site.
For a chosen site in TYPO3, follow these steps:
- In the typoscript template for the site, load the "Headless - Mixed mode JSON response" setup file instead of the default headless one.
- Set
headlessflag to a value of2in the site configuration file or configure the flag via editor in the Site's management backend.
The mixed mode flag (value of 2) instructs the EXT:headless extension to additionally check for the Accept header with a value of application/json when processing requests to the particular site in the TYPO3 instance.
- In cases where a request lacks the
Acceptheader orAccepthas a different value thanapplication/json, TYPO3 will respond with HTML content (standard TYPO3's response). - In cases where a request's header
Acceptmatches the value ofapplication/json, TYPO3 will respond with a JSON response.
Development for this extension is happening as part of the TYPO3 PWA initiative, see https://typo3.org/community/teams/typo3-development/initiatives/pwa/ If you have any questions, join the #initiative-headless-pwa Slack channel.
A special thanks goes to macopedia.com company, which is sponsoring development of this solution.