heimrichhannot/contao-watchlist-bundle

This utility bundle offers a flexible watchlist for the Contao CMS.

3.9.3 2024-10-25 08:20 UTC

Requires

• php: ^7.4 || ^8.0
• ext-json: *
• ext-zip: *
• contao/core-bundle: ^4.9
• doctrine/dbal: ^2.10 || ^3.0
• heimrichhannot/contao-encore-contracts: ^1.0
• heimrichhannot/contao-inserttagcollection-bundle: ^1.1
• heimrichhannot/contao-twig-support-bundle: ^1.6
• heimrichhannot/contao-utils-bundle: ^2.199
• symfony/config: ^4.4 || ^5.4
• symfony/dependency-injection: ^4.4 || ^5.4
• symfony/event-dispatcher-contracts: ^1.0 || ^2.0 || ^3.0
• symfony/http-foundation: ^4.4 || ^5.4
• symfony/http-kernel: ^4.4 || ^5.4
• symfony/routing: ^4.4 || ^5.4
• symfony/translation-contracts: ^1.0 || ^2.0 || ^3.0

LGPL-3.0-or-later

• Heimrich & Hannot

• contao
• watchlist

README

This utility bundle offers a flexible watch list for the Contao CMS.

Features

• add files or arbitrary contao database entities like tl_news or tl_member to a watch list
• watch lists can be viewed in the contao backend, as well
• ajax handling for a fluent usage (data is always kept up-to-date)
• integrating the watch list is as easy as assigning a frontend module to a layout section and adding links by using insert tags
• download the files added to a watch list as a ZIP archive
• contains clean templates without css styling and templates prepared with bootstrap 5 css classes
• share watch lists via link (also to public) and copy to clipboard

Impressions

Watch list in frontend (here: bootstrap 5 template with modal integration)

Installation & configuration

1. Run composer require heimrichhannot/contao-watchlist-bundle and update your database.
2. Create a watch list config (select bootstrap 5 templates if applicable).
3. Important: Assign the watch list config to your root page.
4. Create a frontend module of type watchlist and add it to a layout area of your website so that it comes with each and every sub page. Select bootstrap 5 custom template if needed.
5. Identify the template you'd like to integrate a link for adding this item to the watch list. Common situations are:
   1. ce_download.html5
   2. ce_downloads.html5
   3. news_full.html5
   4. ...
6. Integrate the link for adding an item to the current watch list to any template by using inserttag or WatchlistLinkGenerator service.

Item types

A watch list in the context of this bundle can have multiple types of items:

1. File: Any file in the contao file manager
2. Entity: Any database record (aka "entity"), e.g. tl_news, tl_member -> downloads aren't possible at the moment

Sharing watch lists

1. Do the steps mentioned in "Installation & configuration"
2. Create a target page for shared watch lists.
3. In your watch list config activate the sharing feature.
4. Create the list module for the share page. You have 2 options:
   1. For simpler needs and file-only watch lists: Create a frontend module of the type "watchlist_share_list". This module fulfills simple needs. Image watch list items are downloadable, entity items are reachable by link.
   2. For more complex needs (like internal areas, filtering, ...): Create a list using heimrichhannot/contao-list-bundle and a reader using heimrichhannot/contao-reader-bundle.

      1. Activate the option actAsWatchlistShareTarget in the list and reader configs.

      2. Make sure, the detailsUrl in the list item template contains the watchlist GET parameter. For example, you could create a block for the detailsUrl, extend your default template and override the detailsUrl:

         {% block detailsUrl %}
         {{ detailsUrl }}?watchlist={{ app.request.get('watchlist') }}
         {% endblock %}

5. Place the module created in the previous step on the page created in the second page.

Permission handling

A watch list is private to its owner. Who is the owner depends on the context, the watch list is used in:

Hint: As watch lists are currently not transferable from session to member, consider showing the watch list only after login. If you have no frontend login situation, you can ignore that, of course.

Insert tags

The following new insert tags are available. These take into account the translated jumpTo url and alias.

Developers

WatchlistLinkGenerator

Add the "Add to watchlist" button from your code:

use Contao\Template;
use HeimrichHannot\WatchlistBundle\Generator\WatchlistLinkGenerator;

function templateListener(Template $template, WatchlistLinkGenerator $linkGenerator) {
    $template->addButton = $linkGenerator->generateAddFileLink($template->singleSrc, $template->fileTitle);
}

Symfony Events

JavaScript events