diff --git a/CHANGELOG.md b/CHANGELOG.md index 363d050..1fa34c7 100644 --- 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 index 853b1cf..03f3b3c 100644 --- 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 index f1f37ee..fa40f92 100644 --- 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 index 024f412..5d41c9b 100644 --- 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 index c035436..a5e17fa 100644 --- 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,7 +82,7 @@ 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 @@ -89,7 +90,7 @@ public function __toString(): string * @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,7 +134,7 @@ 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 @@ -141,7 +142,7 @@ public function __construct(array|Element|Location $locations = [], array $optio * @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 index 9c16bd2..0005733 100644 --- 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) {