heimrichhannot / contao-reader-bundle
This bundle offers a generic reader module to use with arbitrary contao entities containing standard reader specific functionality like field output, images and auto_item handling.
Installs: 4 437
Dependents: 2
Suggesters: 4
Security: 0
Stars: 3
Watchers: 5
Forks: 1
Open Issues: 3
Type:contao-bundle
Requires
- php: ^7.4 || ^8.0
- contao/core-bundle: ^4.9
- doctrine/dbal: ^2.10 || ^3.0
- heimrichhannot/contao-be_explanation-bundle: ^2.2
- heimrichhannot/contao-config-element-type-bundle: ^0.2
- heimrichhannot/contao-entity-filter-bundle: ^1.0
- heimrichhannot/contao-filter-bundle: ^1.0
- heimrichhannot/contao-request-bundle: ^1.3
- heimrichhannot/contao-status_messages: ^1.0|^2.0
- heimrichhannot/contao-twig-support-bundle: ^0.2|^1.0
- heimrichhannot/contao-utils-bundle: ^2.206
- symfony/config: ^4.4||^5.4
- symfony/console: ^4.4||^5.4
- symfony/dependency-injection: ^4.4||^5.4
- symfony/event-dispatcher: ^4.4||^5.4
- symfony/event-dispatcher-contracts: ^1.0 || ^2.0 || ^3.0
- symfony/filesystem: ^4.4||^5.4
- symfony/http-foundation: ^4.4||^5.4
- symfony/http-kernel: ^4.4||^5.4
- symfony/polyfill-php80: ^v1.26.0
- symfony/routing: ^4.4||^5.4
- symfony/service-contracts: ^1.0 || ^2.0 || ^3.0
- symfony/translation: ^4.4||^5.4
- symfony/translation-contracts: ^1.1.6||^2||^3
Requires (Dev)
- contao/manager-plugin: ^2.0
- contao/test-case: 1.1.*
- friendsofphp/php-cs-fixer: ^2.2
- php-http/guzzle6-adapter: ^1.1
- php-http/message-factory: ^1.0.2
- phpunit/php-token-stream: ^1.4|^2.0|^3.0
- phpunit/phpunit: ^6.5
- phpunit/phpunit-mock-objects: ^4.0|^5.0
- satooshi/php-coveralls: ^2.0
- symfony/phpunit-bridge: ^3.2
Suggests
- heimrichhannot/contao-list-bundle: Offers a generic list module.
Conflicts
- heimrichhannot/contao-head-bundle: <1.10.0
- heimrichhannot/contao-list-bundle: <1.51.0
- dev-master
- 1.42.3
- 1.42.2
- 1.42.1
- 1.42.0
- 1.41.4
- 1.41.3
- 1.41.2
- 1.41.1
- 1.41.0
- 1.40.1
- 1.40.0
- 1.39.5
- 1.39.4
- 1.39.3
- 1.39.2
- 1.39.1
- 1.39.0
- 1.38.3
- 1.38.2
- 1.38.1
- 1.38.0
- 1.37.0
- 1.36.2
- 1.36.1
- 1.36.0
- 1.35.1
- 1.35.0
- 1.34.0
- 1.33.2
- 1.33.1
- 1.33.0
- v1.32.x-dev
- 1.32.1
- 1.32.0
- 1.31.1
- 1.31.0
- 1.30.4
- 1.30.3
- 1.30.2
- 1.30.1
- 1.30.0
- 1.29.1
- 1.29.0
- 1.28.0
- 1.27.2
- 1.27.1
- 1.27.0
- 1.26.1
- 1.26.0
- 1.25.1
- 1.25.0
- 1.24.0
- 1.23.8
- 1.23.7
- 1.23.6
- 1.23.5
- 1.23.4
- 1.23.2
- 1.23.1
- 1.23.0
- 1.22.0
- 1.21.0
- 1.20.2
- 1.20.1
- 1.20.0
- 1.19.1
- 1.19.0
- 1.18.0
- 1.16.0
- 1.15.2
- 1.15.1
- 1.15.0
- 1.14.0
- 1.13.0
- 1.12.1
- 1.12.0
- 1.11.2
- 1.11.1
- 1.11.0
- 1.10.1
- 1.10.0
- 1.9.0
- 1.8.7
- 1.8.6
- 1.8.5
- 1.8.4
- 1.8.3
- 1.8.2
- 1.8.1
- 1.8.0
- 1.7.0
- 1.6.2
- 1.6.1
- 1.6.0
- 1.5.4
- 1.5.3
- 1.5.2
- 1.5.1
- 1.5.0
- 1.4.0
- 1.3.4
- 1.3.3
- 1.3.2
- 1.3.1
- 1.3.0
- 1.2.1
- 1.2.0
- 1.1.1
- 1.1.0
- 1.0.0
- 1.0.0-beta90
- 1.0.0-beta89
- 1.0.0-beta88
- 1.0.0-beta87
- 1.0.0-beta86
- 1.0.0-beta85
- 1.0.0-beta84
- 1.0.0-beta83
- 1.0.0-beta82
- 1.0.0-beta81
- 1.0.0-beta80
- 1.0.0-beta79
- 1.0.0-beta78
- 1.0.0-beta77
- 1.0.0-beta76
- 1.0.0-beta75
- 1.0.0-beta74
- 1.0.0-beta73
- 1.0.0-beta72
- 1.0.0-beta71
- 1.0.0-beta70
- 1.0.0-beta69
- 1.0.0-beta68
- 1.0.0-beta67
- 1.0.0-beta66
- 1.0.0-beta65
- 1.0.0-beta64
- 1.0.0-beta63
- 1.0.0-beta62
- 1.0.0-beta61
- 1.0.0-beta60
- 1.0.0-beta59
- 1.0.0-beta58
- 1.0.0-beta57
- 1.0.0-beta56
- 1.0.0-beta55
- 1.0.0-beta54
- 1.0.0-beta53
- 1.0.0-beta52
- 1.0.0-beta51
- 1.0.0-beta50
- 1.0.0-beta49
- 1.0.0-beta48
- 1.0.0-beta47
- 1.0.0-beta46
- 1.0.0-beta45
- 1.0.0-beta44
- 1.0.0-beta43
- 1.0.0-beta42
- 1.0.0-beta41
- 1.0.0-beta40
- 1.0.0-beta39
- 1.0.0-beta38
- 1.0.0-beta37
- 1.0.0-beta36
- 1.0.0-beta35
- 1.0.0-beta34
- 1.0.0-beta33
- 1.0.0-beta32
- 1.0.0-beta31
- 1.0.0-beta30
- 1.0.0-beta29
- 1.0.0-beta28
- 1.0.0-beta27
- 1.0.0-beta26
- 1.0.0-beta25
- 1.0.0-beta24
- 1.0.0-beta23
- 1.0.0-beta22
- 1.0.0-beta21
- 1.0.0-beta20
- 1.0.0-beta19
- 1.0.0-beta18
- 1.0.0-beta17
- 1.0.0-beta16
- 1.0.0-beta15
- 1.0.0-beta14
- 1.0.0-beta13
- 1.0.0-beta12
- 1.0.0-beta11
- 1.0.0-beta10
- 1.0.0-beta9
- 1.0.0-beta8
- 1.0.0-beta7
- 1.0.0-beta6
- 1.0.0-beta5
- 1.0.0-beta4
- 1.0.0-beta3
- 1.0.0-beta2
- 1.0.0-beta
- dev-feature/update_head_bundle_integration
- dev-fix-comment-type
- dev-dev
This package is auto-updated.
Last update: 2024-12-07 10:47:43 UTC
README
This bundle offers a generic reader module to use with arbitrary contao entities containing standard reader specific functionality like field output, images and auto_item handling.
It makes it possible to generate readers not only for events, news or faq's but with every DCA you like.
Features
- generic reader module: output entities of arbitrary DCA entities
- dedicated and inheritable reader config entities that can be assigned to one or many modules
- twig support for templates
- Head Bundle support
Hint: This module can greatly be used with heimrichhannot/contao-list-bundle which can display lists of arbitrary DCA entities
Impressions
Reader configuration
Concepts
Inheritable reader configuration
Since reader configuration can be lots of data sometimes we decided to outsource it into a dedicated DCA entity. These entities can be assigned to one or even multiple reader modules in a reusable way.
In addition it's possible to create reader configs that inherit from other reader configs. Hence overriding a single option while keeping everything else is possible.
The Item class
Every database record output in a reader (e.g. an event) is modelled and wrapped by the Item
class. The concrete class is DefaultItem
. You can imagine
the item as a kind of ORM (object-relational-mapping).
The most important properties of an item are the arrays raw
and formatted
which also can be iterated in the reader item template:
raw
: contains the raw database valuesformatted
: contains the formatted representation of the raw values
Example: Let's say a database record has a field startDate
which holds a unix timestamp of the date chosen in the backend.
Then raw
contains this unix timestamp and formatted
contains the pretty printed date according to the dateFormat
set in
the contao settings, i.e. "2020-09-12".
The reader bundle uses the method FormUtil::prepareSpecialValueForOutput()
in heimrichhannot/contao-utils-bundle
for handling special values. It supports a wide range of types of special values:
- date/time fields
- arrays
- fields with
options
,options_callback
and entries in the DCA'sreference
key - binary fields (files, images, ...)
- ...
You can access both of these arrays in your reader item twig template as you normally would in twig:
{% for field, value in raw %} {% endfor %} {% for field, value in formatted %} {% endfor %}
CAUTION: By default all values of a database record are formatted and accessible in the item template. As you can imagine
if some of the fields have thousands of options, the process of formatting can take some time and can reduce the peformance
of your website. Hence you always should limit the formatted fields and only format these you really need. You can adjust that
in the reader configuration (field limitFormattedFields
).
For convenience reasons you can also access the field values like so in your twig template:
{{ fieldname }}
If you configured the field fieldname
to be formatted, it will contain the formatted value. If not, the raw one. If
it's formatted, you can still access its raw value by using:
{{ raw.fieldname }}
Reader config elements
Every reader config can have one or more reader config elements. These are designed to specify things that can occur multiple times (e.g. because there are many fields of one type).
Currently build-in reader config element types:
Other bundle can add reader config elements as well. Some examples:
Image
You can add images either as formatted value of, if you also like to have additional features like image size processing or automatic placeholders if no image is set, you can use the image reader config element.
After the configuration you can output it as follows in your item template:
{% if images|default and images.myImage|default %} {{ include('@HeimrichHannotContaoUtils/image.html.twig', images.myImage) }} {% endif %}
IMPORTANT: Note that by default the generated picture elements are added to an array called images
. If your DCA
contains a field with the same name, you need to specify a different container name like e.g. resizedImages
(using overrideTemplateContainerVariable
).
Templates
There are two ways to define your templates.
1. By Prefix
The first one is to simply deploy twig templates inside any templates
or bundles views
directory with the following prefixes:
reader_item_
item_
news_
event_
More prefixes can be defined, see 2nd way.
2. By config.yml
The second on is to extend the config.yml
and define a strict template:
Plugin.php
<?php
class Plugin implements BundlePluginInterface, ExtensionPluginInterface
{
/**
* {@inheritdoc}
*/
public function getBundles(ParserInterface $parser)
{
…
}
/**
* {@inheritdoc}
*/
public function getExtensionConfig($extensionName, array $extensionConfigs, ContainerBuilder $container)
{
return ContainerUtil::mergeConfigFile(
'huh_reader',
$extensionName,
$extensionConfigs,
__DIR__ .'/../Resources/config/config.yml'
);
}
}
config.yml
huh:
reader:
templates:
item:
- { name: default, template: "@HeimrichHannotContaoReader/reader_item_default.html.twig" }
item_prefixes:
- reader_item_
- item_
- news_
- event_
Developers
Events
Reader config elements
It is easy to add new reader config elements.
-
Create a class that implements
HeimrichHannot\ConfigElementTypeBundle\ConfigElementType\ConfigElementTypeInterface
-
Register the class as service with service tag
huh.reader.config_element_type
-
Add a friendly type name (translation) into the
$GLOBALS['TL_LANG']['tl_reader_config_element']['reference']
variable$lang['reference'][\HeimrichHannot\ReaderBundle\ConfigElementType\CommentConfigElementType::getType()] = 'Comment';