Developed with love by KnpLabs Hire us for your project!
43

contao-content-api-bundle

by DieSchittigs

Contao JSON-API

Contao Content API

We at Die Schittigs love
Contao, but the web moves
forward and static HTML templating just doesn't cut it anymore. Thus we came up
with an easily digestible JSON-API to access Contao content via JavaScript
(or anything else that can handle JSON).

With the Contao Content API it is possible to write the entire Frontend of your
website in React.js, Angular, vue, or any other
JS-framework. All while still using the great Contao Backend.

Requirements

You'll need an up-and-running Contao 4.4.x installation.
Please note that the API is not compatible with Contao 3.x.

Installation

Install composer if you haven't already,
enter this command in the main directory of your Contao installation:

composer require dieschittigs/contao-content-api

Contao Content API is now installed and ready to use.

Usage

Once installed, the following routes are available:

/api/sitemap

Gets the sitemap including the root pages.

Example

/api/sitemap/flat

Gets all pages as key value pairings where the key is the URL.

Example

/api/urls[?file=sitemap]

Gets all URLs from the generated sitemap XML(s). If you define a file, only that XML will be parsed.

Example

/api/page?url=/about/team.html

Gets the page, including all articles and contents at the url.

Example

/api/newsreader?url=/news/detail/new-website.html

Gets the news reader content from the url

Example

/api/?url=/page/or/newsarticle.html

Tries to get the page at the url, and contents from any reader

Example

/api/user

Gets the logged-in frontend user, if available.

Example

/api/module?id=5

Gets the content of a module by id

Example

/api/text?file=tl_news,modules

Gets the content of a language file by filename(s)

Example

/api/file?path=files/uploads&depth=2

Gets the file or directory at path and also it's children, limited by depth

Example

All routes also take the additional lang parameter (e.g. ?lang=de). If you
need to override the language.

Configuration

Disabling the API

Edit your parameters.yml.

parameters:
…
content_api_enabled:
    false
…

The API routes are now all disabled. This may be helpful if you only
want to use the classes included in the bundle.

Response headers

Edit your parameters.yml.

parameters:
…
content_api_headers:
    'Access-Control-Allow-Origin': 'https://mysite.org'
…

These headers will be added to all responses from the API.

Custom readers

Contao has the concept of Reader Module (e.g. News Reader). These can be
inserted anywhere inside of an article where they read the URL to display
their contents. If you want to add additional Reader Modules, you can do
so by adding them in your parameters.yml.

parameters:
…
    content_api_readers:
        newsreader: NewsModel
        blogreader: BlogModel
…

Please note that the second parameter is the model class, not the module
class. The new reader is now available at

/api/blogreader?url=/blog/detail/on-the-topic.html

or, if you want to include the whole page, at

/api?url=/blog/detail/on-the-topic.html

Internally the API tries to instantiate the model with the alias found in the url.
It also tries to add all ContentModels it can find.

Hooks

We provide some basic hooks:

class Hook{

    // $GLOBALS['TL_HOOKS']['apiBeforeInit']
    public static apiBeforeInit(Request $request){
        return $request
    }

    // $GLOBALS['TL_HOOKS']['apiAfterInit']
    public static apiAfterInit(Request $request){
        return $request
    }

    // $GLOBALS['TL_HOOKS']['apiContaoJson']
    public static apiContaoJson(ContaoJson $contaoJson, mixed $data){
        if($data instanceof ContentModel){
            $contaoJson->data = null;
            // End of the line
            return false;
        }
        // Do your thing, ContaoJson
        return true;

    }

    // $GLOBALS['TL_HOOKS']['apiResponse']
    public static apiResponse(mixed $data){
        $data->tamperedWith = true;
        return $data;

    }
}

Documentation

The classes crafted for the API might be a good starting point if you want
to build anything on top of Contao.

Check out the docs here

Contribution

Bug reports and pull requests are very welcome :)


© Die Schittigs GmbH 2019

Copyright 2019 Die Schittigs GmbH

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  • Add compiled HTML to each content element
    By web-flow, 1 month ago
  • Bugfix
    By web-flow, 1 month ago
  • Bugfix
    By web-flow, 1 month ago
  • Bugfix
    By web-flow, 1 month ago
  • extracting language from url was bugged
    By , 2 months ago
  • added example return payloads
    By saibotd, 2 months ago
  • rewrite
    By saibotd, 2 months ago
  • Removed URL replacing code
    By web-flow, 2 months ago
  • Removed URL replacing code
    By web-flow, 2 months ago
  • Wrong root page
    By web-flow, 3 months ago
  • get form model in article
    By saibotd, 3 months ago
  • use JSON_NUMERIC_CHECK and JSON_UNESCAPED_UNICODE
    By saibotd, 3 months ago
  • more file information
    By saibotd, 3 months ago
  • added mimetype detection
    By saibotd, 3 months ago
  • more file information
    By saibotd, 3 months ago
  • Insert tags are replaced now
    By saibotd, 3 months ago
  • better merging of urls
    By saibotd, 3 months ago
  • Merge branch 'master' of github.com:DieSchittigs/contao-content-api-bundle
    By saibotd, 3 months ago
  • Added a new route to get a list of all URLs
    By saibotd, 3 months ago
  • Correct page order in sitemap
    By web-flow, 3 months ago
  • Added "Access-Control-Allow-Origin" Header
    By web-flow, 3 months ago
  • Load all pages (for all root pages) when not providing a language
    By web-flow, 3 months ago
  • Update composer.json
    By web-flow, 3 months ago
  • Fix urls for images
    By web-flow, 3 months ago
  • Use the controller function `addImageToTemplate` to get a much better result for image files
    By web-flow, 3 months ago
  • Merge pull request #7 from padarom/master
    By web-flow, 10 months ago
  • Use Symfony's provided Route annotation
    By padarom, 10 months ago
  • Fixed a bug where $val was wrongfully overwritten
    By web-flow, 1 year ago
  • Add resized image to response
    By web-flow, 1 year ago
  • Merge branch 'master' of https://github.com/DieSchittigs/contao-content-api-bundle
    By saibotd, 1 year ago