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 

  1. Rendering the content element. The content element (CType t3events_eventlist or t3events_performancelist) 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).
  2. Choosing the action. Without plugin arguments in the URL the plugin runs its list action. A link from a list carries the action show and the record (tx_t3events_eventlist[event]=12 or, with readable URLs, /detail/jazz-evening), so the plugin on the detail page runs the detail action.
  3. 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).
  4. Visitor input. If the request contains a sort or filter selection (overwriteDemand), it is stored in the visitor's session. If it contains resetDemand, the stored selection is removed.
  5. 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.
  6. 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.
  7. 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:

  1. plugin.tx_t3events.settings from TypoScript.
  2. 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.
  3. t3events then builds the settings for the controller (event or performance) and the action (list, show):

    • settings.<controller>.search and settings.<controller>.notify,
    • overlaid by settings.<controller>.<action>.*,
    • overlaid by all top-level settings (TypoScript and plugin options).

So plugin.tx_t3events.settings.performance.list.order becomes settings.order for a performance list, unless the plugin options contain order (also if empty). The nested settings stay available, so templates can read settings.event.list.paginate as well.

Consequently, TypoScript defaults for fields of the plugin form (order, maxItems, 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
Copied!

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)
maxItems limit limit
period, respectEndDate period constraint period constraint
periodType, periodStart, periodDuration, periodStartDate, periodEndDate date range of the period specific date range of the period specific
genres, venues, eventTypes genre, venue, eventType genres, venues, eventTypes (of the event)
categories, categoryConjunction categories, categoryConjunction categories, categoryConjunction
statuses, excludeSelectedStatuses ignored status constraint

Further demand properties have no field in the plugin form but can be set in TypoScript (plugin.tx_t3events.settings.<name> or per controller and action):

Setting Effect
offset Skip the first records.
storagePages Comma separated page uids to select records from, instead of the storage folder of the plugin.
audiences Comma separated audience uids.
eventLocations Comma separated event location uids (performance list only).
constraintsConjunction Conjunction of the audience constraints of the performance list.

Storage folder 

Event lists select events from the Extbase storage folder:

  • plugin.tx_t3events.persistence.storagePid (constant of the same name), optionally with plugin.tx_t3events.persistence.recursive;
  • the field Record storage page (tt_content.pages) 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;
  • the setting storagePages (see above), which takes precedence.

Performance lists ignore the storage folder by default and select performances from all pages. Enable the extension configuration respectPerformanceStoragePage to apply the storage folder to them. In addition, storagePages 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.

Sorting 

The order is a comma separated list of <property>|<direction>, 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|asc,performances.begin|asc date|asc,begin|asc
Date descending performances.date|desc,performances.begin|desc date|desc,begin|desc
Title event.headline|asc – not valid for events in 4.0, see below event.headline|asc
Manual sorting sorting|asc: the order of the events in the storage folder sorting|asc: 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 sortBy and sortDirection 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
}
Copied!

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.event.list.paginate is set (default 1) with settings.event.list.itemsPerPage items per page (default 5; not set in the default TypoScript). The page number is the argument currentPage (with readable URLs /page-2). 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_t3events_domain_model_event and tx_t3events_domain_model_event_<uid>, 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_content.t3events_eventlist.20 and tt_content.t3events_performancelist.20:

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
}
Copied!

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 overwriteDemand 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
overwriteDemand[sortBy], [sortDirection] Order by the property (e.g. performances.date or headline) in the direction asc or desc.
overwriteDemand[genre], [venue], [eventType] Restrict to the given uids (comma separated).
overwriteDemand[period], [periodType], [startDate], [endDate] Period as in the plugin; specific without a start date falls back to all.
overwriteDemand[search][subject] Search term (see Search).
resetDemand=1 Remove the stored selection.

The sort form is part of the event list template. It is shown if

  • settings.event.list.showSortBy is set (default 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.