Add support for primary field and media field references

Author: doekenorg

docs/docs/SDK/10-creating-dataviews.md

@@ -12,7 +12,8 @@ To create a `DataView` you need to call any of the named constructors available:
 - `DataView::list()` - Creates a DataView with a `list` view type.
 - `DataView::grid()` - Creates a DataView with a `grid` view type.
 
-The view type used will be the default view type, but you can add support for other view types by declaring the other view types that are supported:
+The view type used will be the default view type, but you can add support for other view types by declaring the other
+view types that are supported:
 
 ```php
 $dataview = DataView::table( ... )->supports( View::Grid(), View::List() );
@@ -31,6 +32,32 @@ named constructors will have all the required parameters, and make for a fluent
 
 A DataView has a public API for applying some default settings to the component.
 
+### Primary Field
+
+A DataView can have a primary field. This field is highlighted in each layout type; and can not be hidden. To set this
+primary field, you call the `primary_field( Field $field )` method on the instance, and reference the field object you
+want to use.
+
+```php
+$fields = [
+    TextField::create( 'author' , 'Author' ),
+    $title_field => TextField( 'title', 'Title' ), // Store the field instance in a separate variable.
+];
+
+$dataview = DataView::table( 'table', $data_source, $fields )
+    ->primary_field( $title_field ); // Set the reference to the field instance.
+```
+
+### Media Field
+
+Both the `Grid` and `List` layout try to show a media object for every result. By default, it will look for the first 
+media field available on the fields; but you can also specify a specific field in case you have multiple images.
+
+```php
+$dataview = DataView::table( ... )
+    ->media_field( $media_field ); // Set the reference to the field instance.
+```
+
 ### Searching
 
 By default, search is enabled on the DataView component. To disable this, you can call the `disable_search()` method on
@@ -126,8 +153,8 @@ the `->deletable( string $label, ?callable $callback = null)` method on the Data
 
 :::note
 
-This functionality requires the DataView to have a `MutableDataSource` which `can_delete()`. This data source is 
-responsible for deleting the results. If the data source can not delete results, calling the `deleteable()` method will 
+This functionality requires the DataView to have a `MutableDataSource` which `can_delete()`. This data source is
+responsible for deleting the results. If the data source can not delete results, calling the `deleteable()` method will
 not do anything.
 
 :::

src/DataView/DataView.php

@@ -104,6 +104,24 @@ final class DataView {
 	 */
 	private Pagination $pagination;
 
+	/**
+	 * The field used as a media field.
+	 *
+	 * @since $ver$
+	 *
+	 * @var Field|null
+	 */
+	private ?Field $media_field = null;
+
+	/**
+	 * The field used as the primary field.
+	 *
+	 * @since $ver$
+	 *
+	 * @var Field|null
+	 */
+	private ?Field $primary_field = null;
+
 	/**
 	 * Whether the DataView supports searching.
 	 *
@@ -428,17 +446,17 @@ private function default_layouts(): array {
 	 * @return string[] The field IDs.
 	 */
 	private function get_field_ids( ?callable $filter = null ): array {
-		$hidden_fields = [];
+		$field_ids = [];
 
 		foreach ( $this->directory_fields as $field ) {
 			if ( $filter && ! $filter( $field ) ) {
 				continue;
 			}
 
-			$hidden_fields[] = $field->uuid();
+			$field_ids[] = $field->uuid();
 		}
 
-		return $hidden_fields;
+		return $field_ids;
 	}
 
 	/**
@@ -651,17 +669,69 @@ private function add_view_fields( Field ...$fields ): void {
 	 */
 	private function layout( View $view ): array {
 		$output = [];
+
+		if ( $this->primary_field ) {
+			$output['primaryField'] = $this->primary_field->uuid();
+		}
+
 		if ( $view->equals( View::Grid() ) ) {
 			$output['badgeFields']  = $this->get_field_ids( static fn( Field $field ): bool => $field->is_badge() );
 			$output['columnFields'] = $this->get_field_ids( static fn( Field $field ): bool => $field->is_column() );
 		}
 
+		if ( ! $view->equals( View::Table() ) ) {
+			$output['mediaField'] = $this->get_media_field_id();
+		}
+
+		return array_filter( $output );
+	}
+
+	/**
+	 * Returns an instance of the DataView with a primary field.
+	 *
+	 * @since $ver$
+	 *
+	 * @param Field|null $field The primary field.
+	 *
+	 * @return self The DataView.
+	 */
+	public function primary_field( ?Field $field ): self {
+		$this->primary_field = $field;
+
+		return $this;
+	}
+
+	/**
+	 * Returns an instance of the DataView with a media field.
+	 *
+	 * @since $ver$
+	 *
+	 * @param Field|null $field The media field.
+	 *
+	 * @return self The DataView.
+	 */
+	public function media_field( ?Field $field ): self {
+		$this->media_field = $field && $field->is_media_field() ? $field : null;
+
+		return $this;
+	}
+
+	/**
+	 * Returns the id of the media field.
+	 *
+	 * If no media field is provided, it will assume the first media field it comes across.
+	 *
+	 * @return string The media field id.
+	 */
+	private function get_media_field_id(): string {
+		if ( $this->media_field ) {
+			return $this->media_field->uuid();
+		}
+
 		$image_fields = $this->get_field_ids(
 			static fn( Field $field ): bool => $field->is_media_field(),
 		);
 
-		$output['mediaField'] = reset( $image_fields );
-
-		return array_filter( $output );
+		return $image_fields ? reset( $image_fields ) : '';
 	}
 }

tests/DataView/DataViewTest.php

@@ -5,6 +5,8 @@
 use DataKit\DataViews\Data\ArrayDataSource;
 use DataKit\DataViews\DataView\DataView;
 use DataKit\DataViews\Field\EnumField;
+use DataKit\DataViews\Field\ImageField;
+use DataKit\DataViews\Field\TextField;
 use PHPUnit\Framework\TestCase;
 
 /**
@@ -18,7 +20,7 @@ final class DataViewTest extends TestCase {
 	 *
 	 * @since $ver$
 	 */
-	public function test_to_js() : void {
+	public function test_to_js(): void {
 		$view = DataView::table(
 			'test',
 			new ArrayDataSource(
@@ -39,4 +41,35 @@ public function test_to_js() : void {
 
 		self::assertStringContainsString( $expected, $view->to_js() );
 	}
+
+	/**
+	 * Test case for {@see DataView::media_field()} and {@see DataView::primary_field()}.
+	 *
+	 * @since $ver$
+	 */
+	public function test_primary_and_media_fields(): void {
+		$data_source = new ArrayDataSource( 'array', [] );
+		$fields      = [
+			$primary_field = TextField::create( 'primary', 'Primary' ),
+			$image_field = ImageField::create( 'image', 'Normal image field' ),
+			$media_field = ImageField::create( 'media', 'Media field' ),
+		];
+
+		$table   = DataView::table( 'table', $data_source, $fields )->media_field( $media_field );
+		$table_2 = DataView::table( 'table-2', $data_source, $fields )->primary_field( $primary_field );
+		$grid    = DataView::grid( 'grid', $data_source, $fields );
+		$grid_2  = DataView::grid( 'grid-2', $data_source, $fields )
+			->primary_field( $primary_field )
+			->media_field( $media_field );
+
+		self::assertArrayNotHasKey( 'primaryField', $table->to_array()['view']['layout'] );
+		self::assertArrayNotHasKey( 'mediaField', $table->to_array()['view']['layout'] );
+		self::assertArrayHasKey( 'primaryField', $table_2->to_array()['view']['layout'] );
+
+		self::assertArrayNotHasKey( 'primaryField', $grid->to_array()['view']['layout'] );
+		self::assertArrayHasKey( 'primaryField', $grid_2->to_array()['view']['layout'] );
+
+		self::assertSame( $image_field->uuid(), $grid->to_array()['view']['layout']['mediaField'] );
+		self::assertSame( $media_field->uuid(), $grid_2->to_array()['view']['layout']['mediaField'] );
+	}
 }