Post Selection Controller

In Advanced Views, the Selection Controller is a special PHP class allowing you to control the related Post Selection behavior.

Using the Selection Controller, you can do the following:

1. Add extra arguments the Posts Query (WP_Query)

2. Add extra variables to the Selection template

3. Define Selection Ajax actions

4. Define Selection Rest Api actions

If you opted for vanilla PHP templates or Blade templates, you can also load extra fields right inside the template. Though loading extra fields via the Controller is beneficial for advanced cases, as it splits responsibilities and provides access to the PHP-DI instance.

1. How to add custom WP_Query arguments

Post Selection provides a user interface for all the main WP_Query arguments. However, to avoid overloading the user interface, we haven't included all possible arguments.

In advanced cases, you may need to use arguments that are missing from the UI. You can achieve this by using the Post Selection Controller, which can be found under the Template tab of your Post Selection.

In the get_query_arguments() method, you can pass any WP_Query arguments, which will be merged with the foundational query arguments, made based on the settings from the UI.

2. How to add custom template arguments

In the get_variables() method, you can also add any custom variables to your Post Selection template.

Bad use case: your Post Selection queries posts of the current user, and you need to display a user name at the top of the list. Instead of creating a new Layout for displaying the user info, and pasting the Layout's shortcode to the Post Selection template, you use the custom template arguments.

Good use case: your Post Selection queries WooCommerce Products by specific author (seller), and you need to display a live seller's rate that is deducted dynamically, and not available in the User meta.

3. Selection Controller methods

The field with the snippet can be found in the Template tab of your Post Selection.

The snippet is a PHP code, which must return an instance of the Selection_Controller_Base class.

• using the get_variables() method you can pass custom variables to the Post Selection template

• using the get_query_arguments() method you can pass custom arguments to the Post Selection query

• using the get_ajax_response() method you define the Ajax callback for the block. Read more

• using the get_rest_api_response() method you define the Rest api callback

• using the get_custom_arguments() method you can access the custom arguments passed to the shortcode. The field is available in the both methods above.

• using the get_default_variables() method you can access to the default twig variables (that filled out automatically by the plugin)

• using the get_default_query_arguments() method you can access to the default query arguments (that filled out automatically by the plugin)

• using the get_container() method you can access the PHP-DI Container (see the related chapter of this page)

<?php

declare(strict_types=1);

use Org\Wplake\Advanced_Views\Bridge\Controllers\Selection\Selection_Controller_Base;

return new class extends Selection_Controller_Base {
    /**
     * @return array<string,mixed>
     */
    public function get_variables(): array
    {
        return [
            // "another_var" => $this->get_custom_arguments()["another"] ?? "",
        ];
    }

    /**
     * @return array<string,mixed>
     */
    public function get_variables_for_validation(): array
    {
        // it's better to return dummy data here [ "another_var" => "dummy string", ]
        return $this->get_variables();
    }

    public function get_query_arguments(): array
    {
        // https://developer.wordpress.org/reference/classes/wp_query/#parameters
        return [
            // "author" => get_current_user_id(),
            // "post_parent" => $this->get_custom_arguments()["post_parent"] ?? 0,
        ];
    }
    /**
     * @return array<string,mixed>
     */
    public function get_ajax_response(): array
	{
	    // $message = $this->get_container()->get(MyClass::class)->myMethod();
		return [
			// "message" => $message,
		];
	}
	/**
     * @return array<string,mixed>
     */
    public function get_rest_api_response(WP_REST_Request $request): array
	{
	    // $input = $request->get_json_params();
	    // $message = $this->get_container()->get(MyClass::class)->myMethod();
		return [
			// "message" => $message,
		];
	}
};

Tip: if you pass custom variables using the get_variables() method, we recommend changing the get_variables_for_validation() method and return dummy data there.

Advanced Views has the built-in automatic template validation, which is called on the Publish and Update action. There is no sense to return real data in this case, and it's better to return dummy data, to avoid potential issues with missing functions.

For example, if you use WP functions inside, they may be front-end only, and aren't available in the wp-admin area, which will lead to the failed validation.

4. PHP-DI support

PHP-DI is a well-known dependency injection container. If you haven't used it, we recommend checking it out and harnessing its capabilities.

Advanced Views supports PHP-DI out-of-the-box. To simplify access to your theme's PHP class instances inside the PHP Controller instances, you can employ the PHP-DI container. To do this, you need to define the container in your theme using the advanced_views/container hook. Then, you can access it using the get_container() method in any method of the PHP Controller class.

Example

A simple example is below:

1. Define a container in your theme:

<?php

use DI\Container;

$container = new Container();

add_filter( 'acf_views/container', function () use ( $container ) {
	return $container;
} );

3. Request Container inside the Controller:

<?php

declare(strict_types=1);

use Org\Wplake\Advanced_Views\Bridge\Controllers\Selection\Selection_Controller_Base;
use MyTheme\MyClass;

return new class() extends Selection_Controller_Base {
    /**
     * @return array<string,mixed>
     */
    public function get_variables(): array {
       $container = $this->get_container();

       if ( null === $container ) {
          return array();
       }

       $my_class = $container->get( MyClass::class );

       return array(
          'my_var_with_complex_calculation' => $my_class->get_var(),
       );
    }
};

If you're unfamiliar with PHP-DI concepts, the benefits of the code above may be unclear to you. We could replace $container->get with new MyClass() and it would work perfectly. However, the container is a powerful tool, especially for more complex cases.

You won't see a significant benefit if your MyClass has no dependencies. But let's say the class has 2-3 constructor arguments (e.g., a logger and a theme object). To get the MyClass instance, you would need to create those instances initially. Furthermore, one of those arguments may have its own arguments, and your creation code will turn into a multi-line creation.

With PHP-DI, you don't need to worry about the constructor, as PHP-DI will use PHP's reflection feature to get the necessary instances and pass them to the constructor on the fly.

An additional benefit is that the ->get method, unlike ->make, creates the instance only once, reusing it for other calls. This way, you get a smart 'global' variables pool, allowing you to handle dependencies easily and efficiently.

Unlike the singleton pattern, which is considered an anti-pattern, it doesn't turn your code into single-instance classes. You still define constructors, clearly specifying class dependencies, while avoiding the hassle of manual creation.

Additionally, PHP-DI supports and encourages the use of interfaces, so you can call

->get(MapInterface::class)->calculate() in your code, while defining which exact class should be used for each interface in the container configuration.