Filters - Jet\DataListing_Filter

Each data list filter is made up of its own class, which inherits from the Jet\DataListing_Filter abstract class and represents the logic of the filter. Let's show a real filter right away. Let's stay with the event viewer and look at a filter that can be used to filter a list by event type:


namespace JetApplicationModule\EventViewer\Admin;



use Jet\DataListing_Filter;

use Jet\Form;

use Jet\Form_Field_Input;

use Jet\Http_Request;



class Listing_Filter_Event extends DataListing_Filter {



    public const KEY = 'event';



    protected string $event = '';

    

    public function getKey(): string

    {

        return static::KEY;

    }



    public function catchParams(): void

    {

        $this->event = Http_Request::GET()->getString( 'event' );

        $this->listing->setParam( 'event', $this->event );

    }



    public function catchForm( Form $form ): void

    {

        $this->event = $form->field( 'event' )->getValue();

        $this->listing->setParam( 'event', $this->event );

    }



    public function generateFormFields( Form $form ): void

    {

        $field = new Form_Field_Input( 'event', 'Event:' );

        $field->setDefaultValue( $this->event );



        $form->addField( $field );

    }



    public function generateWhere(): void

    {

        if( $this->event ) {

            $this->listing->addFilterWhere( [

                'event' => $this->event,

            ] );

        }

    }



}

So what does the filter need to be able to do:

Catch its parameters - catchParams method
Generate form item definitions for filter form - generateFormFields method
Capture values from the filter form (which is already captured and validated at the given moment) - catchForm method
Generate WHERE part of the query for ORM DataModel - generateWhere method
Each filter must be identified by its unique key.

Filter view script

Each filter has its own view script. To display a filter in a view that displays the corresponding list, the following call is used:


<?=$listing->filter(Listing_Filter_Event::KEY)->renderForm()?>

However, this call will call the view script of the filter, which can be, for example, as follows:


<?php

namespace JetApplicationModule\EventViewer\Admin;



use Jet\MVC_View;



/**

 * @var MVC_View $this

 * @var Listing  $listing

 */

$listing = $this->getRaw( 'listing' );

$filter_form = $listing->getFilterForm();

?>

<?= $filter_form->field( 'event' )->label() ?>

<?= $filter_form->field( 'event' )->input()?>

The name of the view script must match the filter ID key. So in our example it is event.phtml.

Method Overview

Method	Meaning of
public setListing( DataListing $listing ) : void	The list automatically sets the filter reference to itself when passing the filter. This method is used for this purpose.
public getListing( ) : DataListing	Returns the instance of the data list to which the filter belongs.
abstract public getKey( ) : string	Returns a unique key identifying the filter. It is recommended to implement as follows: `class Listing_Filter_Event extends DataListing_Filter { public const KEY = 'event'; public function getKey(): string { return static::KEY; } }` And then work with the filter as follows: `<?=$listing->filter(Listing_Filter_Event::KEY)->renderForm()?>`
abstract public catchParams( ) : void	This method is used to capture filter parameters, such as GET parameters from a URL.
abstract public generateFormFields( Form $form ) : void	The method is used to generate form fields of the filter.
abstract public catchForm( Form $form ) : void	The method is used to capture values from the filter form. It is called when the form is already captured and validated.
abstract public generateWhere( ) : void	Generates the WHERE part of the query for the ORM DataModel to filter the data itself.
public renderForm( ) : string	Renders the appropriate filter. The default implementation is as follows: `$view = $this->listing->getFilterView(); $view->setVar('filter', $this ); $view->setVar('listing', $this->listing); return $view->render( $this->getKey() );` Which implies: The Jet\MVC_View instance is held by the list instance. The filter only takes it over. The name of the view script in the default implementation corresponds to the filter key. The view script has a list instance and a filter instance.

Prepared filters

To make your work easier, Jet includes several pre-made filters that you just need to finish implementing. Here is a list of them:

Jet\DataListing_Filter_Search	Classic text search box.
Jet\DataListing_Filter_DateInterval	Date range definition (from - till). Two input fields.
Jet\DataListing_Filter_DateTimeInterval	Date and time range definition (from - till). Two input fields.
Jet\DataListing_Filter_OptionSelect	Select from defined options (select box).