How the plugins work
This chapter follows a request through a list plugin: from the content element to the database query and the template. It explains which setting has which effect and where settings from the backend, from TypoScript and from the visitor meet.
Overview
- Rendering the content element. The content element (
CTypet3events_oreventlist t3events_) is rendered by Extbase. If the option Don't cache plugin contents is set, the plugin is rendered on every request, otherwise its output is part of the cached page (see Caching).performancelist - Choosing the action. Without plugin arguments in the URL the plugin
runs its list action. A link from a list carries the action
showand the record (tx_or, with readable URLs,t3events_ eventlist [event]=12 /detail/), so the plugin on the detail page runs the detail action.jazz- evening - Merging the settings. TypoScript settings, the plugin options of the content element and controller specific TypoScript are merged into one settings array (see Settings: TypoScript and plugin options).
- Visitor input. If the request contains a sort or filter selection
(
overwrite), it is stored in the visitor's session. If it containsDemand reset, the stored selection is removed.Demand - Building the demand. A demand object is created from the settings (see From settings to demand). The visitor's selection from the request or, if the request has none, from the session is applied on top.
- Querying. The repository converts the demand into constraints (see Filtering), orderings (see Sorting) and a limit, restricted to the storage folder (see Storage folder). Hidden records, records outside their start and stop time and records for other user groups are always excluded.
- Rendering. The result is assigned to the template together with the settings and the demand. Listeners of PSR-14 events can change the query before it runs and the template variables before rendering (see PSR-14 events).
Settings: TypoScript and plugin options
Settings come from three places. Later ones win:
plugin.from TypoScript.tx_ t3events. settings - The plugin options of the content element (FlexForm). Extbase merges them over the TypoScript settings. Empty values count: a field that is stored empty in the FlexForm replaces a TypoScript value of the same name.
-
t3events then builds the settings for the controller (
eventorperformance) and the action (list,show):settings.<controller>.andsearch settings.<controller>.,notify - overlaid by
settings.<controller>.<action>.*, - overlaid by all top-level settings (TypoScript and plugin options).
So plugin. becomes
settings. for a performance list, unless the plugin options contain
order (also if empty). The nested settings stay available, so templates
can read settings. as well.
Consequently, TypoScript defaults for fields of the plugin form (order,
max, period …) only apply to content elements that were never
saved with the form. TypoScript is suited for settings without a form field.
Example: all event lists show events for the audience with uid 2 only:
plugin.tx_t3events.settings.event.list.audiences = 2
From settings to demand
The demand object describes what to select. Each setting whose name matches a property of the demand is applied; empty values are skipped. A few names are mapped:
| Setting (plugin option) | Event list (event demand) | Performance list (performance demand) |
|---|---|---|
order | order | order, date options rewritten to the performance fields
(date, begin) |
max | limit | limit |
period, respect | period constraint | period constraint |
period, period, period,
period, period | date range of the period specific | date range of the period specific |
genres, venues, event | genre, venue, event | genres, venues, event (of the event) |
categories, category | categories, category | categories, category |
statuses, exclude | ignored | status constraint |
Further demand properties have no field in the plugin form but can be set in
TypoScript (plugin. or per controller and
action):
| Setting | Effect |
|---|---|
offset | Skip the first records. |
storage | Comma separated page uids to select records from, instead of the storage folder of the plugin. |
audiences | Comma separated audience uids. |
event | Comma separated event location uids (performance list only). |
constraints | Conjunction of the audience constraints of the performance list. |
Storage folder
Event lists select events from the Extbase storage folder:
plugin.(constant of the same name), optionally withtx_ t3events. persistence. storage Pid plugin.;tx_ t3events. persistence. recursive - the field Record storage page (
tt_) of the content element, if it has a value. The plugin form does not contain this field in 4.0, but values stored by earlier versions are still used;content. pages - the setting
storage(see above), which takes precedence.Pages
Performance lists ignore the storage folder by default and select
performances from all pages. Enable the extension configuration
respect to apply the storage folder to them. In
addition, storage restricts performances to the given pages.
Performances of a hidden event are never listed. Start and stop time and the user groups of the event are not checked for performances, only those of the performance itself.
Filtering
All constraints of a list are combined with AND.
Period
The period compares the date fields of the records with today (00:00 in the server's time zone). Event lists use the date and end date of the event's performances: an event matches if one of its performances matches. Performance lists use the date and end date of the performance.
| Period | respect end date off | respect end date on |
|---|---|---|
| all | no constraint | no constraint |
| future only | date ≥ today | date ≥ today, or end date ≥ today |
| past only | date ≤ today | date ≤ today and end date ≤ today |
| specific | start ≤ date ≤ end | inside the range: date ≥ start and end date ≤ end, or the performance began before the range and ends inside it |
Today is included in future only and in past only. A performance without end date satisfies all end date conditions.
For the period specific, constraint by defines the range:
| Constraint by | Start of the range | End of the range |
|---|---|---|
| Days | today + Start days | today + Duration days |
| Months | first day of the current month + Start months | today + Duration months |
| Years | January 1st of the current year + Start years | today + Duration years |
| Date | the date Start | the date End, or one day after Start if empty |
Start may be negative. The end of the range is counted from today, not from the start; for example Months, Start -1, Duration 1 selects from the first day of last month to one month from today (see Known problems).
Classification
Venues, Genres, Event types and Categories restrict the list to records with the selected values. Empty fields do not restrict.
| Conjunction | Event list | Performance list |
|---|---|---|
| Or (default) | The event matches any selected venue, genre, event type or category. | Within each field, any selected value matches; the fields are combined with AND (e.g. one of the genres and one of the categories). |
| And | The event matches all selected values of all fields. | Within each field, all selected values must match; the fields are combined with AND. |
Performance lists check the classification of the performance's event.
Status
Only performance lists evaluate Status: with exclude selected statuses off, only performances with one of the selected statuses are listed, with the option on, all others.
Search
The search term of the filter form (overwrite) is
searched in the fields of settings. (default
headline,subtitle,teaser,description,keywords) or, for performances,
settings. (the same fields of the event).
A record matches if one field contains the term.
Sorting
The order is a comma separated list of <property>, direction
asc or desc (asc if omitted). Properties are Extbase property
paths of the listed record.
| Option sort by | Event list | Performance list |
|---|---|---|
| Date | performances. | date |
| Date descending | performances. | date |
| Title | event. – not valid for events in 4.0, see below | event. |
| Manual sorting | sorting: the order of the events in the storage folder | sorting: the order of the performances in their event |
| none | no explicit order | sorting ascending |
The plugin option wins over TypoScript. A TypoScript value for order has
no effect once the content element has been saved, because the plugin
options then contain order (possibly empty) and replace it (see
Settings: TypoScript and plugin options).
For other orders, leave sort by empty in the plugin and set sort and
sort in TypoScript. They are applied before order and are
not part of the plugin form. Example, events by title:
plugin.tx_t3events.settings.event.list {
sortBy = headline
sortDirection = asc
}
An event list sorted by date sorts by the dates of the event's performances; an event with several performances appears once.
Limit and pagination
Items count (max) limits the number of records. Without a value the limit is 100, also for paginated lists.
Event lists are paginated if settings. is set
(default 1) with settings. items per page
(default 5; not set in the default TypoScript). The page number is the
argument current (with readable URLs /page-). Performance lists
are not paginated in 4.0.
Detail view
The links of a list point to the Detail Page, action show. Both lists
link to the detail view of the event; the detail page must contain an
Event list plugin. Its own settings are irrelevant for the detail view.
The event is resolved by its uid or, with readable URLs, by its URL segment. If it does not exist, is hidden or outside its start/stop time, the plugin redirects with HTTP status 301 to the List Page of the detail plugin or, if empty, to the current page (see Known problems).
The detail view of a performance (action show of the performance list)
exists, but the default templates do not link to it.
Caching
By default the plugins are cached with the page. The plugin output depends
only on the plugin options, the TypoScript and the record that is shown, so
the page cache is correct. Saving a record clears the pages that show it
(cache tags tx_ and
tx_, the same for performances).
Don't cache plugin contents renders the plugin on every request. t3events
achieves this per content element with a CASE object in its static
template, which replaces tt_ and
tt_:
tt_content.t3events_eventlist.20 = CASE
tt_content.t3events_eventlist.20 {
key.data = flexform : pi_flexform:settings.cache.notCacheable
default < lib.tx_t3events.plugin.eventlist
1 = COA_INT
1.10 < lib.tx_t3events.plugin.eventlist
}
The static template copies the plugin definition of the content rendering, so it must be included after fluid_styled_content (or the site set that defines the content elements). If it is included before, the plugins render nothing.
Use uncached plugins only where visitors change the list (sort form, filter form). On a cached plugin the visitor's selection is not applied.
Sorting and filtering by visitors
Visitors change the list by sending overwrite arguments, with the
sort form of the event list or a filter form in a custom template. The
selection is applied on top of the plugin settings:
| Argument | Effect |
|---|---|
overwrite, [sort | Order by the property (e.g. performances. or
headline) in the direction asc or desc. |
overwrite, [venue], [event | Restrict to the given uids (comma separated). |
overwrite, [period, [start,
[end | Period as in the plugin; specific without a start date falls back to all. |
overwrite | Search term (see Search). |
reset | Remove the stored selection. |
The sort form is part of the event list template. It is shown if
settings.is set (defaultevent. list. show Sort By 1),- the plugin is not cached (Don't cache plugin contents), and
- the list is not empty.
It offers Date and Title in both directions and preselects the order of the plugin.
The selection is stored in the visitor's session and applied to the next requests of all event lists (or all performance lists) of the site until it is reset or the session ends. Submitting the sort form replaces the stored selection. If a site has several lists of the same type, give visitors a reset link or avoid uncached lists with forms on more than one page.
Note
The filter form of earlier versions (quick menu) cannot be selected in
the plugin form in 4.0. A custom template can render the partial
Common/ with the same arguments. See Known problems
for the limitations of the form.