.. _demands:

=======
Demands
=======

A demand is a configuration object used by the repository to decide which
news records should be fetched.

The default demand class implementation for the frontend output of news
is :php:`GeorgRinger\News\Domain\Model\Dto\NewsDemand`. It has a couple of
useful properties that can be used to filter news records, for example
:php:`$categories`, :php:`$searchFields`, :php:`$author` and many more.

There is also the property :php:`$customSettings` an array of custom settings
by extensions. You should use your extension name as key in this array.

Demand objects can be changed in a couple of ways, see below:

URL Parameter
=============

The URL parameter :code:`overwriteDemand` can be used to override properties
of the demand.

You can set this parameter in a Fluid link (see
:ref:`Set overwriteDemand in Frontend <overwriteDemand-in-frontend>`) or via
TypoScript in a typolink (See
:ref:`TypoScript reference: typolink <t3tsref:typolink>`).

It would even be possible to configure a :ref:`LinkHandler <linkhandler>`
for this parameter.

.. important::

   The checkbox :guilabel:`Disable override demand` in the list plugin
   (Tab Additional) must **not** be set to allow overriding the properties.

   Additionally the TypoScript setting
   :ref:`settings.disableOverrideDemand <tsDisableOverrideDemand>` must be set to
   :code:`0`.

Via TypoScript
==============

TypoScript can be used to define a class containing a
:ref:`custom implementation <demand_custom>`
of the demand object. This can be achieved by the TypoScript setting
:ref:`settings.demandClass <tsDemandClass>`.

Custom controllers
==================

The demand object can be used in a custom controller used in an extension
extending EXT:news. Read more about using a demand object in a custom
controller:
:ref:`Extension based on EXT:news: FilterController.php <extension_custom_controller>`.

Events
======

Multiple events can change or use demand objects. For example the events of
the main actions in the :php:`NewsController`, for example
:php:`NewsListActionEvent` and :php:`NewsDetailActionEvent`. For more
information refer to the chapter :ref:`Events <events>`.

.. _demand_custom:

Custom demand class
===================

All custom frontend news demand classes must extend
:php:`GeorgRinger\News\Domain\Model\Dto\NewsDemand`. The demand object is
a simple configuration object. It should contain no business logic. For each
property there must be a setter and a getter.

Example:

.. code-block:: php

   <?php

   namespace Vendor\MyNews\Domain\Model\Dto;

   use \GeorgRinger\News\Domain\Model\Dto\NewsDemand;

   class MyNewsDemand extends NewsDemand {

      /**
      * @var string
      */
      protected $myCustomField = '';

      /**
      * Set myCustomField
      *
      * @param string $myCustomField
      * @return NewsDemand
      */
      public function setMyCustomField(string $myCustomField): NewsDemand
      {
         $this->myCustomField = $myCustomField;
         return $this;
      }

      /**
      * Get myCustomField
      *
      * @return string
      */
      public function getMyCustomField(): string
      {
         return $this->myCustomField;
      }
   }