Added support for element collections

doublesecretagency · Dec 18, 2023 · 65fb0dc · 65fb0dc
1 parent 7159335
commit 65fb0dc
Show file tree

Hide file tree

Showing 6 changed files with 62 additions and 40 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,10 @@
 # Changelog
 
+## Unreleased
+
+### Added
+- Added support for [element collections](https://craftcms.com/docs/4.x/element-queries.html#collect). 
+
 ## 4.3.8 - 2023-10-18
 
 ### Changed

diff --git a/docs/dynamic-maps/locations.md b/docs/dynamic-maps/locations.md
@@ -17,39 +17,39 @@ The `locations` value can be a set of [coordinates](/models/coordinates/), or an
 
 :::code
 ```js
-// Just one set of coordinates
+// As a single set of coordinates
 var locations = {
     'lat':  32.3113966,
     'lng': -64.7527469
 };
 
-// An array of coordinate sets
+// As an array of coordinate sets
 var locations = [
     {'lat': 37.2430548, 'lng': -115.7930198},
     {'lat': 57.3009274, 'lng':   -4.4496567}
 ];
 ```
 ```twig
-{# Just one set of coordinates #}
+{# As a single set of coordinates #}
 {% set locations = {
     'lat':  32.3113966,
     'lng': -64.7527469
 } %}
 
-{# An array of coordinate sets #}
+{# As an array of coordinate sets #}
 {% set locations = [
     {'lat': 37.2430548, 'lng': -115.7930198},
     {'lat': 57.3009274, 'lng':   -4.4496567}
 ] %}
 ```
 ```php
-// Just one set of coordinates
+// As a single set of coordinates
 $locations = [
     'lat' =>  32.3113966,
     'lng' => -64.7527469
 ];
 
-// An array of coordinate sets
+// As an array of coordinate sets
 $locations = [
     ['lat' => 37.2430548, 'lng' => -115.7930198],
     ['lat' => 57.3009274, 'lng' =>   -4.4496567]
@@ -70,20 +70,20 @@ The `locations` value can be set as an individual [Address Model](/models/addres
 
 :::code
 ```twig
-{# Just one Address Model #}
+{# As a single Address Model #}
 {% set locations = entry.myAddressField %}
 
-{# An array of Address Models #}
+{# As an array of Address Models #}
 {% set locations = [
     entry.homeAddress,
     entry.businessAddress
 ] %}
 ```
 ```php
-// Just one Address Model
+// As a single Address Model
 $locations = $entry->myAddressField;
 
-// An array of Address Models
+// As an array of Address Models
 $locations = [
     $entry->homeAddress,
     $entry->businessAddress
@@ -96,22 +96,28 @@ $locations = [
 
 ## Elements
 
-The `locations` value can be set as an individual [Element](https://craftcms.com/docs/3.x/elements.html), or as an array of Elements. This can include any native Element Types (ie: Entries, Categories, Users, etc), as well as any custom Element Types introduced by other plugins or modules.
+The `locations` value can be set as an individual [Element](https://craftcms.com/docs/3.x/elements.html), or as an array (or collection) of Elements. This can include any native Element Types (ie: Entries, Categories, Users, etc), as well as any custom Element Types introduced by other plugins or modules.
 
 :::code
 ```twig
-{# Just one Element #}
+{# As a single Element #}
 {% set locations = entry %}
 
-{# An array of Elements #}
+{# As an array of Elements #}
 {% set locations = craft.entries.all() %}
+
+{# As a collection of Elements #}
+{% set locations = craft.entries.collect() %}
 ```
 ```php
-// Just one Element
+// As a single Element
 $locations = $entry;
 
-// An array of Elements
+// As an array of Elements
 $locations = Entry::find()->all();
+
+// As a collection of Elements
+$locations = Entry::find()->collect();
 ```
 :::
 

diff --git a/src/helpers/GoogleMaps.php b/src/helpers/GoogleMaps.php
@@ -13,6 +13,7 @@
 
 use Craft;
 use craft\base\Element;
+use craft\elements\ElementCollection;
 use doublesecretagency\googlemaps\GoogleMapsPlugin;
 use doublesecretagency\googlemaps\models\DynamicMap;
 use doublesecretagency\googlemaps\models\Location;
@@ -97,11 +98,11 @@ public static function loadAssets(array $params = []): void
     /**
      * Create a new Dynamic Map object.
      *
-     * @param array|Element|Location $locations
+     * @param array|ElementCollection|Element|Location $locations
      * @param array $options
      * @return DynamicMap
      */
-    public static function map(array|Element|Location $locations = [], array $options = []): DynamicMap
+    public static function map(array|ElementCollection|Element|Location $locations = [], array $options = []): DynamicMap
     {
         // Create a new map object
         $map = new DynamicMap($locations, $options);
@@ -142,11 +143,11 @@ public static function getMap(string $mapId): ?DynamicMap
     /**
      * Create a new Static Map object.
      *
-     * @param array|Element|Location $locations
+     * @param array|ElementCollection|Element|Location $locations
      * @param array $options
      * @return StaticMap
      */
-    public static function img(array|Element|Location $locations = [], array $options = []): StaticMap
+    public static function img(array|ElementCollection|Element|Location $locations = [], array $options = []): StaticMap
     {
         return new StaticMap($locations, $options);
     }

diff --git a/src/helpers/MapHelper.php b/src/helpers/MapHelper.php
@@ -13,6 +13,7 @@
 
 use Craft;
 use craft\base\Element;
+use craft\elements\ElementCollection;
 use craft\helpers\StringHelper;
 use craft\models\FieldLayout;
 use doublesecretagency\googlemaps\fields\AddressField;
@@ -49,11 +50,11 @@ public static function generateId(?string $prefix = null): string
      * Coordinates will always be returned inside a parent array,
      * to compensate for Elements with multiple Address Fields.
      *
-     * @param array|Element|Location $locations
+     * @param array|ElementCollection|Element|Location $locations
      * @param array $options
      * @return array Collection of coordinate sets
      */
-    public static function extractCoords(array|Element|Location $locations, array $options = []): array
+    public static function extractCoords(array|ElementCollection|Element|Location $locations, array $options = []): array
     {
         // If it's an Address Model, return the coordinates w/ optional ID
         if ($locations instanceof Address) {
@@ -97,8 +98,15 @@ public static function extractCoords(array|Element|Location $locations, array $o
             return [$locations];
         }
 
-        // Force array syntax
+        // If it's an Element Collection
+        if ($locations instanceof ElementCollection) {
+            // Convert to an array
+            $locations = $locations->all();
+        }
+
+        // If still not an array
         if (!is_array($locations)) {
+            // Create single-item array
             $locations = [$locations];
         }
 

diff --git a/src/models/DynamicMap.php b/src/models/DynamicMap.php
@@ -14,6 +14,7 @@
 use Craft;
 use craft\base\Element;
 use craft\base\Model;
+use craft\elements\ElementCollection;
 use craft\helpers\Html;
 use craft\helpers\Json;
 use craft\helpers\StringHelper;
@@ -81,15 +82,15 @@ public function __toString(): string
     /**
      * Initialize a Dynamic Map object.
      *
-     * @param array|Element|Location $locations
+     * @param array|ElementCollection|Element|Location $locations
      * @param array $options
      * @param array $config
      * @throws Exception
      * @throws LoaderError
      * @throws RuntimeError
      * @throws SyntaxError
      */
-    public function __construct(array|Element|Location $locations = [], array $options = [], array $config = [])
+    public function __construct(array|ElementCollection|Element|Location $locations = [], array $options = [], array $config = [])
     {
         // Call parent constructor
         parent::__construct($config);
@@ -133,15 +134,15 @@ public function __construct(array|Element|Location $locations = [], array $optio
     /**
      * Add one or more markers to the map.
      *
-     * @param array|Element|Location $locations
+     * @param array|ElementCollection|Element|Location $locations
      * @param array $options
      * @return $this
      * @throws Exception
      * @throws LoaderError
      * @throws RuntimeError
      * @throws SyntaxError
      */
-    public function markers(array|Element|Location $locations, array $options = []): DynamicMap
+    public function markers(array|ElementCollection|Element|Location $locations, array $options = []): DynamicMap
     {
         // If no locations were specified, bail
         if (!$locations) {
@@ -175,11 +176,11 @@ public function markers(array|Element|Location $locations, array $options = []):
     /**
      * Add one or more circles to the map.
      *
-     * @param array|Element|Location $locations
+     * @param array|ElementCollection|Element|Location $locations
      * @param array $options
      * @return $this
      */
-    public function circles(array|Element|Location $locations, array $options = []): DynamicMap
+    public function circles(array|ElementCollection|Element|Location $locations, array $options = []): DynamicMap
     {
         // If no locations were specified, bail
         if (!$locations) {
@@ -609,14 +610,14 @@ public function getDna(): array
     /**
      * Create individual markers one at a time.
      *
-     * @param array|Element|Location $locations
+     * @param array|ElementCollection|Element|Location $locations
      * @param array $options
      * @throws Exception
      * @throws LoaderError
      * @throws RuntimeError
      * @throws SyntaxError
      */
-    private function _individualMarkers(array|Element|Location $locations, array $options): void
+    private function _individualMarkers(array|ElementCollection|Element|Location $locations, array $options): void
     {
         // Initialize infoWindowOptions
         $options = $options ?? [];
@@ -709,14 +710,14 @@ private function _markerClick(string $markerId, array $options): void
     /**
      * Parse a dynamic marker string.
      *
-     * @param array|Element|Location $location
+     * @param array|ElementCollection|Element|Location $location
      * @param string $string
      * @throws Exception
      * @throws LoaderError
      * @throws SyntaxError
      * @throws Throwable
      */
-    private function _parseLocationString(array|Element|Location $location, string &$string): void
+    private function _parseLocationString(array|ElementCollection|Element|Location $location, string &$string): void
     {
         // Get view services
         $view = Craft::$app->getView();
@@ -737,11 +738,11 @@ private function _parseLocationString(array|Element|Location $location, string &
     /**
      * Creates a single marker with a corresponding info window.
      *
-     * @param array|Element|Location $location
+     * @param array|ElementCollection|Element|Location $location
      * @param array $options
      * @param bool $isCoords
      */
-    private function _markerInfoWindow(array|Element|Location $location, array &$options, bool $isCoords): void
+    private function _markerInfoWindow(array|ElementCollection|Element|Location $location, array &$options, bool $isCoords): void
     {
         // Initialize marker data
         $infoWindow = [

diff --git a/src/models/StaticMap.php b/src/models/StaticMap.php
@@ -13,6 +13,7 @@
 
 use craft\base\Element;
 use craft\base\Model;
+use craft\elements\ElementCollection;
 use craft\helpers\Html;
 use craft\helpers\Template;
 use doublesecretagency\googlemaps\helpers\GoogleMaps;
@@ -69,11 +70,11 @@ public function __toString(): string
     /**
      * Initialize a Static Map object.
      *
-     * @param array|Element|Location $locations
+     * @param array|ElementCollection|Element|Location $locations
      * @param array $options
      * @param array $config
      */
-    public function __construct(array|Element|Location $locations = [], array $options = [], array $config = [])
+    public function __construct(array|ElementCollection|Element|Location $locations = [], array $options = [], array $config = [])
     {
         // Ensure options are a valid array
         if (!$options || !is_array($options)) {
@@ -107,11 +108,11 @@ public function __construct(array|Element|Location $locations = [], array $optio
     /**
      * Add one or more markers to the map.
      *
-     * @param array|Element|Location $locations
+     * @param array|ElementCollection|Element|Location $locations
      * @param array $options
      * @return $this
      */
-    public function markers(array|Element|Location $locations, array $options = []): StaticMap
+    public function markers(array|ElementCollection|Element|Location $locations, array $options = []): StaticMap
     {
         // If no locations were specified, bail
         if (!$locations) {
@@ -165,11 +166,11 @@ public function markers(array|Element|Location $locations, array $options = []):
     /**
      * Add a defined path to the map.
      *
-     * @param array|Element|Location $points
+     * @param array|ElementCollection|Element|Location $points
      * @param array $options
      * @return $this
      */
-    public function path(array|Element|Location $points, array $options = []): StaticMap
+    public function path(array|ElementCollection|Element|Location $points, array $options = []): StaticMap
     {
         // If no points were specified, bail
         if (!$points) {