2017 © Pedro Peláez
 

contao-bundle contao-watchlist-bundle

Project bundle

image

heimrichhannot/contao-watchlist-bundle

Project bundle

  • Tuesday, July 24, 2018
  • by digitales@heimrich-hannot.de
  • Repository
  • 5 Watchers
  • 0 Stars
  • 44 Installations
  • PHP
  • 0 Dependents
  • 0 Suggesters
  • 0 Forks
  • 0 Open issues
  • 5 Versions
  • 29 % Grown

The README.md

Contao Watchlist Bundle

A contao watchlist for download elements. It enables users to collect items (e.g. downloads, images) into an watchlist and download them later or altogether as zip file., (*1)

Version 2 of this bundle is an major rewrite of this bundle and not complete backwards compatible. A migration tool is not given, but you can view the major changes in the UPGRADE document., (*2)

This bundle is still in alpha, as not all parts of the bundle are rewritten and tested. Currently only the parts for using it with content elements is mostly done and well tested., (*3)

Features

  • users can collect item into watchlist
  • download watchlist items and watchlist
  • use single or multiple watchlist
  • generate link to watchlist
  • define durability of the watchlist
  • users of the same group can use same watchlist
  • Easily add watchlist support to your entity/modules/contentelement/list
    • download and downloads content element supported out of the box
  • Frontend output is high customizable to be used with your frontend framework
    • a simple base layout and bootstrap 4 already bundled
  • List Bundle support
  • Encore Bundle support
  • Notification Center support

Setup

  1. Install via composer, (*4)

    composer require heimrichhannot/contao-watchlist-bundle
    

    Make sure version 2 is used., (*5)

  2. Update the database., (*6)

  3. Create an watchlist config (Contao Backend -> System -> Watchlist configuration)., (*7)

  4. Enable watchlist in your root page and select the created watchlist config., (*8)

  5. Create an watchlist module and select the created config., (*9)

  6. Optional: If you have custom templates for download(s) content element, output $this->addToWatchlistButton['html'], (*10)

Usage

List bundle

To add an "add to watchlist" button to your list entries, add the watchlist list config element type to the list configuration and output the corresponding template variable., (*11)

If you want to create a watchlist list (output the content of an watchlist from list bundle), use the auto_item filter config element with pid for a filter on tl_watchlist_item., (*12)

Developers

Configuration

All configuration options including the default values., (*13)

huh_watchlist:
  content_elements:
    - download
    - downloads
  downloadFileItems:
    - { name: default, class: HeimrichHannot\WatchlistBundle\Item\DownloadItemFile }
  downloadEntityItems:
    - { name: default, class: HeimrichHannot\WatchlistBundle\Item\DownloadItemEntity }
  watchlistFileItems:
    - { name: default, class: HeimrichHannot\WatchlistBundle\Item\WatchlistItemFile }
  watchlistEntityItems:
    - { name: default, class: HeimrichHannot\WatchlistBundle\Item\WatchlistItemEntity }

Add custom frontend layouts

Due alpha state of this bundle, no all templates supported by the frontend framework system. Old templates must be overridden the "contao way"., (*14)

  1. Create an frontend framework class extending AbstractWatchlistFrontendFramework and register it as service with huh.watchlist.framework service tag., (*15)

  2. Create twig templates for your framework with framework type suffix, e.g. watchlist_window_base.html.twig for base framework or watchlist_window_bs4.html.twig for bootstrap 4., (*16)

    Available Templates (please consider the base templates for available template variables:, (*17)

    Template Description
    open_watchlist_window The open watchlist button (used in the watchlist module)
    watchlist_action Action button. Used for 'add to watchlist' and 'download all' action.
    watchlist_item_parent_list Renders the parent pagePath if grouped
    watchlist_window The watchlist window

    Not defined template for a framework will fallback to the base templates, if the Framework class extends AbstractWatchlistFrontendFramework., (*18)

  3. Create js event listener for adding watchlist button count watchlist_create_count_element_[FRAMEWORK TYPE], if non exist. Event is dispatched on every element that need an updated count., (*19)

    Example:, (*20)

    // init event listener
    class MyEventListener {
        init () 
        {
            document.addEventListener('watchlist_create_count_element_base', this.onWatchlistCreateCountElementBase);
        }
    
        // event listener method
        onWatchlistCreateCountElementBase(event)
        {
            let badge = document.createElement('span');
            badge.setAttribute('class', event.detail.cssClass);
            badge.textContent = event.detail.count;
            event.target.appendChild(badge);
        }
    }
    
  4. Optional: create js event listener for open watchlist action, e.g. trigger the event toggle, (*21)

    Example:, (*22)

    class MyEventListener {
        init () 
        {
            document.addEventListener('watchlist_window_open_bs4', this.onWatchlistWindowOpenBs4);
        }
    
        /**
         * @param {CustomEvent} event
         */
        onWatchlistWindowOpenBs4(event)
        {
            let modalElement = event.detail.container.querySelector('.modal');
            if (null !== modalElement) {
                $(modalElement).modal();
            }
        }
    }
    

Add watchlist support to your entity

  1. Register your content element:, (*23)

    huh_watchlist:
      content_elements:
        - myContentElement
    
  2. Optional: Add DCA fields to your element palette:, (*24)

    // tl_content.php
    
    $dca['palettes']['myContentElement'] = str_replace(
       '{template_legend',
       '{watchlist_legend},disableWatchlist,overrideWatchlistConfig;{template_legend', 
       $dca['palettes']['myContentElement']
    );
    
  3. Create an event listener for the huh.watchlist.event.prepare_element event. Use the event to create the AddToWatchlist button and add it to the element template. To generate the buttons, call PartialTemplateBuilder::generate(new AddToWatchlistPartialTemplate()). See example for more details., (*25)

    # Register event listener
    services:
      MyVendor\MyBundle\EventListener\WatchlistPrepareElementListener:
        tags:
          - { name: kernel.event_listener, event: huh.watchlist.event.prepare_element }
    
    <?php
    use HeimrichHannot\WatchlistBundle\Event\WatchlistPrepareElementEvent;
    use HeimrichHannot\WatchlistBundle\PartialTemplate\AddToWatchlistPartialTemplate;
    use HeimrichHannot\WatchlistBundle\PartialTemplate\PartialTemplateBuilder;
    
    class WatchlistPrepareElementListener
    {
        /** @var PartialTemplateBuilder */
        protected $templateBuilder;
    
        public function __construct(PartialTemplateBuilder $templateBuilder) 
        {
            $this->templateBuilder = $templateBuilder;
        }
    
        public function onHuhWatchlistEventPrepareElement(WatchlistPrepareElementEvent $event)
        {
            if ($event->getTemplate()->type === 'myContentElement') {
                $event->getTemplate()->addToWatchlistButton = $this->templateBuilder->generate(
                    new AddToWatchlistActionPartialTemplate(
                        $event->getConfiguration(),
                        'tl_content',
                        $event->getTemplate()->singleSRC,
                        $event->getTemplate()->fileName
                    )
                );
           }
        }
    }
    

The Versions