# Custom Data (Pro)

{% hint style="info" %}
The page below describes the Custom Data feature for _Card_. You can read about the Custom Data feature for _View_ [here](https://docs.advanced-views.com/display-content/custom-data-pro).
{% endhint %}

## About the feature

Using the Custom Data feature you can add extra arguments to the _Card_ query, and extra variables to the _Card_ template.&#x20;

### 1. Custom query arguments

_Card_ provides a user interface for all the main [WP\_Query arguments](https://developer.wordpress.org/reference/classes/wp_query/#parameters). However, to avoid overloading the user interface, we haven't included all possible arguments.&#x20;

In advanced cases, you may need to use arguments that are missing from the UI. In the Pro Edition, you can achieve this by using the Custom Data feature, which can be found under the **Advanced tab** of your _Card_ settings.

This feature allows you to extend the current _Card_ [WP\_Query arguments](https://developer.wordpress.org/reference/classes/wp_query/#parameters) by merging them with arguments returned from a custom PHP snippet. The data return should return an associative array, which will be merged with the settings from the UI.

### 2. Custom template arguments

Using this feature, you can also add any custom variables to your _Card_ template.&#x20;

{% hint style="info" %}
Tip: Use the custom template arguments only for data that isn't supported by Advanced Views.&#x20;

**Bad use case**: your _Card_ queries posts of the current user, and you need to display a user name in top of the list. Instead of creating a new _View_ for displaying the user info, and pasting _View's_ shortcode to the _Card_ template, you use the custom template arguments.

**Good use case**: your _Card_ 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.
{% endhint %}

## Custom Data snippet

The field with the snippet can be found in the **Advanced tab** of your _Card_.

The snippet is a PHP code, which must return an instance of the `Custom_Card_Data` class.&#x20;

* using the `get_variables()` method you can pass custom variables to the _Card_ template&#x20;
* using the `get_query_arguments()` method you can pass custom arguments to the _Card_ query
* using the `get_ajax_response()` method you define the Ajax callback for the block. [Read more](../templates/custom-ajax-and-rest-api-pro)&#x20;
* using the `get_custom_arguments()` method you can access the [custom arguments passed to the shortcode](https://docs.advanced-views.com/shortcode-attributes/common-arguments#id-4.-custom-arguments). 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)&#x20;

```php
<?php

declare(strict_types=1);

use Org\Wplake\Advanced_Views\Pro\Bridge\Cards\Custom_Card_Data;

return new class extends Custom_Card_Data {
    /**
     * @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 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,
	];
     }
};

```

{% hint style="info" %}
Tip: if you pass custom variables using the `get_variables()` method, we recommend to change the `get_variables_for_validation()` method and return dummy data there.

Advanced Views has the built-in automatic template validation, which called on the Save 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.&#x20;
{% endhint %}

## PHP-DI support

[PHP-DI](https://php-di.org/) 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 Custom\_Data 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`](../../customization/filters-and-hooks#container-pro) hook. Then, you can access it using the `get_container()` method in any method of the Custom\_Data class.

### Example

A simple example is below:

#### 1. Define a container in your theme:&#x20;

```php
<?php

use DI\Container;

$container = new Container();

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

#### 3. Request Container inside the Custom\_Data:

```php
<?php

declare(strict_types=1);

use Org\Wplake\Advanced_Views\Pro\Bridge\Cards\Custom_Card_Data;
use MyTheme\MyClass;

return new class() extends Custom_Card_Data {
    /**
     * @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](https://php-di.org/doc/understanding-di.html), 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.&#x20;

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.

{% hint style="info" %}
With PHP-DI, you don't need to worry about the constructor, as PHP-DI will use [PHP's reflection feature](https://www.php.net/manual/en/intro.reflection.php) to get the necessary instances and pass them to the constructor on the fly.
{% endhint %}

An additional benefit is that the `->get` method, [unlike](https://php-di.org/doc/container.html) `->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.&#x20;

{% hint style="info" %}
Unlike the [singleton pattern](https://en.wikipedia.org/wiki/Singleton_pattern), which is [considered an anti-pattern](https://medium.com/@razu.dev/singleton-the-anti-pattern-18fb2bd102c2), 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.
{% endhint %}

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

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