Add QuickStringTrait::entityLabelsSummary() method for summarizing entity labels #675

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - [Refresh map edit layer when WKT is pasted into data input field #670](https://github.com/farmOS/farmOS/pull/670)
+- [Add QuickStringTrait::entityLabelsSummary() method for summarizing entity labels #675](https://github.com/farmOS/farmOS/pull/675)
 
 ### Changed
 

docs/development/module/quick.md

@@ -149,6 +149,10 @@ Available traits and the methods that they provide include:
     Expects a keyed array of strings to concatenate together, along with an
     optional array of keys that should be prioritized in case the full string
     won't fit.
+  - `entityLabelsSummary($entities, $cutoff)` - Generate a summary of entity
+    labels. Example: "Asset 1, Asset 2, Asset 3 (+ 15 more)". Note that this
+    does NOT sanitize the entity labels. It is the responsibility of downstream
+    code to do so, if it is printing text to the page.
 - `QuickTermTrait`
   - `createTerm($values)` - Creates and returns a new term entity from an array
     of values.

modules/core/quick/src/Traits/QuickStringTrait.php

@@ -131,4 +131,38 @@ trait QuickStringTrait {
     return $this->trimString($priority_string, $max_length);
   }
 
+  /**
+   * Generate a summary of entity labels.
+   *
+   * Note that this does NOT sanitize the entity labels. It is the
+   * responsibility of downstream code to do so, if it is printing text to the
+   * page.
+   *
+   * @param array $entities
+   *   An array of entities.
+   * @param int $cutoff
+   *   The number of entity labels to include before summarizing the rest.
+   *   If the number of entities exceeds the cutoff, the rest will be summarized
+   *   as "(+X more)". If the number of entities is less than or equal to the
+   *   cutoff, or if the cutoff is 0, all entity labels will be included.
+   *
+   * @return string
+   *   Returns a string summarizing the entity labels.
+   */
+  protected function entityLabelsSummary(array $entities, $cutoff = 3) {
+    $names = [];
+    foreach ($entities as $entity) {
+      $names[] = $entity->label();
+    }
+    if ($cutoff != 0) {
+      array_splice($names, $cutoff);
+    }
+    $output = implode(', ', $names);
+    $diff = count($entities) - count($names);
+    if ($diff > 0) {
+      $output .= ' (+' . $diff . ' ' . t('more') . ')';
+    }
+    return $output;
+  }
+
 }

modules/core/quick/tests/src/Kernel/QuickStringTest.php

@@ -2,6 +2,8 @@
 
 namespace Drupal\Tests\farm_quick\Kernel;
 
+use Drupal\asset\Entity\Asset;
+use Drupal\asset\Entity\AssetType;
 use Drupal\farm_quick\Traits\QuickStringTrait;
 use Drupal\KernelTests\KernelTestBase;
 
@@ -18,9 +20,20 @@ class QuickStringTest extends KernelTestBase {
    * {@inheritdoc}
    */
   protected static $modules = [
+    'asset',
     'farm_quick',
+    'state_machine',
+    'user',
   ];
 
+  /**
+   * {@inheritdoc}
+   */
+  protected function setUp(): void {
+    parent::setUp();
+    $this->installEntitySchema('asset');
+  }
+
   /**
    * Test trimString() method.
    */
@@ -72,4 +85,49 @@ class QuickStringTest extends KernelTestBase {
     $this->assertEquals('Foo B… Baz', $name);
   }
 
+  /**
+   * Test entityLabelsSummary() method.
+   */
+  public function testEntityLabelsSummary() {
+
+    // Create a test asset type.
+    $asset_type = AssetType::create([
+      'id' => 'test',
+      'label' => 'Test',
+      'workflow' => 'asset_default',
+    ]);
+    $asset_type->save();
+
+    // Create 10 assets with randomly generated names.
+    $assets = [];
+    for ($i = 0; $i < 10; $i++) {
+      $asset = Asset::create([
+        'name' => $this->randomString(),
+        'type' => 'test',
+        'status' => 'active',
+      ]);
+      $asset->save();
+      $assets[] = $asset;
+    }
+
+    // Test default with a cutoff of 3.
+    $expected = $assets[0]->label() . ', ' . $assets[1]->label() . ', ' . $assets[2]->label() . ' (+7 more)';
+    $name_summary = $this->entityLabelsSummary($assets);
+    $this->assertEquals($expected, $name_summary);
+
+    // Test with a cutoff of 1.
+    $expected = $assets[0]->label() . ' (+9 more)';
+    $name_summary = $this->entityLabelsSummary($assets, 1);
+    $this->assertEquals($expected, $name_summary);
+
+    // Test with a cutoff of 0.
+    $labels = [];
+    foreach ($assets as $asset) {
+      $labels[] = $asset->label();
+    }
+    $expected = implode(', ', $labels);
+    $name_summary = $this->entityLabelsSummary($assets, 0);
+    $this->assertEquals($expected, $name_summary);
+  }
+
 }