Add QuickStringTrait::assetNamesSummary() and deprecate farm_log_asset_names_summary() #671

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- [Add QuickStringTrait::assetNamesSummary() and deprecate farm_log_asset_names_summary() #671](https://github.com/farmOS/farmOS/pull/671)
+
 ### Fixed
 
 - [Fix bulk move/group action log names when unsetting location/group #669](https://github.com/farmOS/farmOS/pull/669)

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.
+  - `assetNamesSummary($assets, $cutoff)` - Generate a summary of asset names
+    for use in a log name. Example: "Asset 1, Asset 2, Asset 3 (+ 15 more)".
+    Note that this does NOT sanitize the asset names. It is the responsibility
+    of downstream code to do so, if it is printing the text to the page.
 - `QuickTermTrait`
   - `createTerm($values)` - Creates and returns a new term entity from an array
     of values.

modules/core/log/farm_log.module

@@ -70,6 +70,9 @@ function farm_log_entity_prepare_form(EntityInterface $entity, $operation, FormS
  *
  * @return string
  *   Returns a string summarizing the assets.
+ *
+ * @deprecated in farmOS:2.x and is removed from farmOS:3.x. Use
+ * \Drupal\farm_quick\Traits\QuickStringTrait::assetNamesSummary() instead.
  */
 function farm_log_asset_names_summary(array $assets, $cutoff = 3) {
   /** @var \Drupal\asset\Entity\AssetInterface[] $assets */

modules/core/quick/farm_quick.info.yml

@@ -6,6 +6,7 @@ core_version_requirement: ^9
 dependencies:
   - drupal:taxonomy
   - farm:asset
+  - farm:farm_log
   - farm:farm_log_quantity
   - farm:quantity
   - log:log

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

@@ -131,4 +131,27 @@ trait QuickStringTrait {
     return $this->trimString($priority_string, $max_length);
   }
 
+  /**
+   * Generate a summary of asset names for use in a log name.
+   *
+   * Note that this does NOT sanitize the asset names. It is the responsibility
+   * of downstream code to do so, if it is printing the text to the page.
+   *
+   * @param \Drupal\asset\Entity\AssetInterface[] $assets
+   *   An array of assets.
+   * @param int $cutoff
+   *   The number of asset names to include before summarizing the rest.
+   *   If the number of assets exceeds the cutoff, only the first asset's
+   *   name will be included, and the rest will be summarized as "(+ X more)".
+   *   If the number of assets is less than or equal to the cutoff, or if the
+   *   cutoff is 0, all asset names will be included.
+   *
+   * @return string
+   *   Returns a string summarizing the assets.
+   */
+  function assetNamesSummary(array $assets, $cutoff = 3) {
+    // @todo Move logic from farm_log_asset_names_summary() into here.
+    return farm_log_asset_names_summary($assets, $cutoff);
+  }
+
 }

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,22 @@ class QuickStringTest extends KernelTestBase {
    * {@inheritdoc}
    */
   protected static $modules = [
+    'asset',
+    // @todo Remove this dependency in farmOS 3.x.
+    'farm_log',
     'farm_quick',
+    'state_machine',
+    'user',
   ];
 
+  /**
+   * {@inheritdoc}
+   */
+  protected function setUp(): void {
+    parent::setUp();
+    $this->installEntitySchema('asset');
+  }
+
   /**
    * Test trimString() method.
    */
@@ -72,4 +87,49 @@ class QuickStringTest extends KernelTestBase {
     $this->assertEquals('Foo B… Baz', $name);
   }
 
+  /**
+   * Test assetNamesSummary() method.
+   */
+  public function testAssetNamesSummary() {
+
+    // 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->assetNamesSummary($assets);
+    $this->assertEquals($expected, $name_summary);
+
+    // Test with a cutoff of 1.
+    $expected = $assets[0]->label() . ' (+ 9 more)';
+    $name_summary = $this->assetNamesSummary($assets, 1);
+    $this->assertEquals($expected, $name_summary);
+
+    // Test default with a cutoff of 0.
+    $labels = [];
+    foreach ($assets as $asset) {
+      $labels[] = $asset->label();
+    }
+    $expected = implode(', ', $labels);
+    $name_summary = $this->assetNamesSummary($assets, 0);
+    $this->assertEquals($expected, $name_summary);
+  }
+
 }