Search with result map and list 

Purpose of this extension is, to have a search for locations based on an entered or configured address. The result displays a google map with marker for each location and a list of all locations. On click on a marker an info window with additional information get shown.

Search form 

Result map and list 

Single points of interest 

Its also possible to pre define a single location to display it on the map without search form. This is useful to have map with single point of interest. For developer its also possible to use the plugin in their extension as map renderer for the location.

How geolocations are computed 

Every location gets geocoded with help of google maps api after saving the record in backend. By this its important to know, that the google maps website needs to be reached from the webserver.

The coordinates are stored in the record each time when the record gets saved. If at one point the address gets changed the coordinate gets fetched from the api again.

Search queries get geocoded the same way by the google maps api. To reduce the api requests the coordinates get stored in the session. So if a query gets send another time the api do not get requested again.

Configuration 

CORS settings 

• for backend rendering in locations records the content security policy header needs to be modified to allow loading images via https

  img-src 'self' data: https:;

  Copied!

• for frontend rendering of google AND OS map the csp header needs to be modified to allow script files via https

  script-src 'self' 'unsafe-inline' blob: data: https:;

  Copied!

• in addition the frontend rendering of OS map needs the csp header to allow loading style files via https

  style-src 'self' 'unsafe-inline' https:;

  Copied!

Purpose of Validators 

Validators are a mechanism to ensure that all information given by the user meet the expectation of the extension. Either if the values make sense in terms of format like zip or in required information value like city.

If values need to be enforce your should use the RequiredValidator because this validator does not only check if the value of the configured field is filled but it also serves as a signal for the Required Partial to render the corresponding flag.

All validators are optional, could be set single or may be even assigned multiple times to a field. Despite the concept of extbase you are free to choose how many validators should take care of a value.

Different possibilities of assigning validators 

In case you want to have no validation at all for a field was was configured by default as required you need to empty the associated validators. Look at the example given where the validators of the email gets removed.

plugin.tx_storefinder.settings.validation.zipcode >

plugin.tx_storefinder.settings.validation.zipcode = Evoweb\StoreFinder\Validation\Validator\RequiredValidator

plugin.tx_storefinder.settings.validation.city {
    1 = Evoweb\StoreFinder\Validation\Validator\RequiredValidator
    2 = StringLength
}

Special validators 

The ConstraintValidator is not meant to be used for field validation. This validator is a special construct to make the configuration via TypoScript possible. All others are free to combine. If a validator is only suited for a certain field it will be mentioned in the detail configuration.

Prefixing needed for non extbase validators 

To use the extension validators you need to prefix them in the TypoScript with EvowebStoreFinderValidationValidator. For all validators without this prefix the validation assumes that they are extbase specific validators and use them as such.

Secondly this makes it possible to use custom validators that do not come with extbase or store_finder. Just code your validator and make it available for auto loading (either in an extbase standard path or via ext_autoload.php). Afterwards you are ready to use your validator like in the following example.

plugin.tx_storefinder.settings.validation.create.city {
    1 = Evoweb\StoreFinder\Validation\Validator\RequiredValidator
}

Available validators 

Beside the validators that come with extbase and which are although available in the different processes, the registration come with a set of specific ones that are tailored to the special need. The following lists all validators which are suited for the usage on fields.

Changing geocoding provider 

By using the geocoder-php/geocoder package it's possible to change the geocoding provider.

As default the geocoder-php/google-maps-provider package is required. But it's possible to require different packages in the project composer.json. A list of available provider can be found here geocoder-php/Geocoder

This can be achieved by

composer require geocoder-php/nominatim-provider

Extension configuration 

If you choose to use a different providers it's important to set the provider classname in the field geocoderProvider:

geocoderProvider = Geocoder\Provider\Nominatim\Nominatim

TypoScript constants 

If you want to use the additional provider for geocoding search results too, you need to change the constant

plugin.tx_storefinder.geocoderProvider = Geocoder\Provider\Nominatim\Nominatim

Introduction 

It is possible to use various custom event listener to use custom location loading logic. If you need a modified sorting or locations based on other constraints then the provided, it is possible to override the loading completely.

Adding event listeners 

Add the following code to the Configuration/Services.yaml of your sitepackage to use the example listener.

namespace Evoweb\StoreFinder\EventListener;

use Evoweb\StoreFinder\Controller\Event\MapGetLocationsByConstraintsEvent;
use TYPO3\CMS\Core\Attribute\AsEventListener;

class MapGetLocationsByConstraintsEventListener
{
    #[AsEventListener('storefinder_mapcontroller_locationsfetched', MapGetLocationsByConstraintsEvent::class)]
    public function __invoke(MapGetLocationsByConstraintsEvent $event): void
    {
    }
}

More explanation for your custom event listener can be found in the tutorial <_customEventListener>

Additional configuration 

plugin.tx_storefinder.settings.disableLocationFetchLogic = 1

plugin.tx_storefinder.settings.defaultConstraint.radius = 20

Modify locations in StoreFinderMiddleware 

It's possible to change locations records from store finder middleware before sending the json response. Use the ModifyMiddlewareLocationsListener as an example of how to change values.

The registration got simplified in TYPO3 13.x

use Evoweb\StoreFinder\Middleware\Event\ModifyMiddlewareLocationsEvent;
use TYPO3\CMS\Core\Attribute\AsEventListener;
class ModifyMiddlewareLocationsEventListener
{
    #[AsEventListener('your-extension-identifier', ModifyMiddlewareLocationsEvent::class)]
    public function __invoke(ModifyMiddlewareLocationsEvent $event): void
    {
    }
}

Templates, partials and layouts 

Like every other extbase extension its possible to configure the fluid templates, partials and layout path via typoscript. Beside that is also possible to configure the templates and partials path in the plugin.

plugin.tx_storefinder.view {
    templateRootPath =
    partialRootPath =
    layoutRootPath =
}

ViewHelper 

Beside the default ViewHelper of fluid the extension comes with three additional ViewHelper. These are used to render the search like the form.selectCountries ViewHelper, the map like the minify ViewHelper and select what to render based on the configuration like the format.binaryAnd ViewHelper.

They are used by including the namespace in the file in which the ViewHelper get used.

Register Namespace 

Add the xmlns to the html tag in the template

xmlns:sf="http://typo3.org/ns/Evoweb/StoreFinder/ViewHelpers"

minify ViewHelper 

This ViewHelper gets used to minify the rendered json of the locations in the result map. The purpose is to reduce the traffic and clean the source code. So in stead of making the template unreadable the output gets minified on rendering time.

var mapConfiguration = {<sf:minify>active: true,
        <f:for each="{settings.mapConfiguration}" as="configuration" key="name" iteration="loop">{name}: '{configuration}',</f:for>
    center: {
        lat: <f:format.number decimals="7">{center.latitude}</f:format.number>,
        lng: <f:format.number decimals="7">{center.longitude}</f:format.number>
    },
    zoom: '{center.zoom}'
</sf:minify>};

var mapConfiguration = {active:true,apiV3Layers:'',language:'de',center:{lat:50.1125089,lng:8.6521548},zoom:'11'}

format.binaryAnd ViewHelper 

To be able to select which partial should be rendered its necessary to compare with binary and if the part is check in the plugin. As the f:if ViewHelper is not able to do so, a special ViewHelper is needed for that.

Basically what this means is, that the setting value, in this case showBeforeSearch, is formatted with a logical and for comparison like in the example below. Here we check if the list should be rendered because in the plugin the binary value 4 stands for list.

<f:if condition="{sf:format.binaryAnd(base: 4, content: settings.showBeforeSearch)} == 4">...</f:if>

form.selectCountries 

The countries select ViewHelper fetches the countries from the country provider and renders each country as option. All attributes from the fluid standard form.select are supported. Beside that if the optional attribute allowedCountries is set, only countries matching it get rendered. allowedCountries accepts a comma seperated list of ISO2 country codes.

<sf:form.selectCountries property="country" id="sfrCountry"
    optionValueField="alpha2IsoCode" allowedCountries="{0: 'DE', 1: 'AT'}" />

Installation 

To install the extension go to the "Admin Tools" section and select the "Extension Manager". On the top selectbox choose "Manage Extensions" and enter store_finder in the search field. Click add to install the extensions.

In case your organization have a api console key click the cog afterwards and enter the code in the configuration field.

In rare case that the api url changes and the extensions was not update quick enough you can change the url used for the geocooding in the same configuration. Be aware that this url only gets used in the geocoding process. For the search in the frontend you need to change it in TypoScript too.

TypoScript 

In general its a good idea to add the include static of the extension to you typoscript record. Otherwise its not possible to use the country selector which is used in the default template.

Structure 

Location records can only be added in folders that's why you need to add at least one folder for storage. Additionally you need a page with the store_finder plugin. In the plugin configure your needs. To use locations of the created folder choose it as record storage page on tab behaviour.

Templating 

To change the frontend templates you most likely need to change the partials. These contain of search, map and list part. Copy the folder from the extension to your local path like the fileadmin. To use these copies you can change the path either in the plugin field "Partial path" or via TypoScript:

plugin.tx_storefinder.view.partialRootPaths.50 = ./yourpath/Partials/

API Keys and Map ID 

If you need to geocode coordinates, either on saving a store record or in bulk with the geocode console command you need to add an additional key in TypoScript constants apiConsoleKeyGeocoding. This key will never be visible to any visitors of your page.

There are two keys needed because the key used in geocoding may not be restricted at all. But you also dont want to deliver pages with an key that is not restricted to the domain in frontend rendering, because then it would be possible that others use the key and by that causes you to pay for usage that wasn't by your page.

So, it's advised to have both keys

• apiConsoleKey (protected by restriction for your domains)
• apiConsoleKeyGeocoding (unrestricted for the usage in php)

To obtain a key please visit https://developers.google.com/maps/get-started

In addition each map should have a unique ID. This can be created on this page https://developers.google.com/maps/documentation/get-map-id?hl=de#create-a-map-id.

Key for the frontend 

Key for the geocoding 

Set default coordinates 

In TypoScript setup it's possible to set defaultConstraints these are filled in the constraints object if no search was requested. In the example below the zoom, latitude and longitude values are set and then the coordinates are used to render search results that are near of them.

plugin.tx_storefinder.settings {
   showLocationsForDefaultConstraint = 1
   defaultConstraint {
      zoom = 15
      latitude = 51.5135
      longitude = 7.464
   }
}

Use caching map action 

As of version 6.1.0 a cached map action is available. To use it with custom templates it important to copy the Templates/Map/CachedMap.html to your sitepackage.

In addition to that it's important to add the <sf:cache location="{location}"/> ViewHelper to the Partials/Locations.html to be able to clear cache on adding a location record without manually click the clear cache flash.

Adding custom event listener 

To add an custom listener, add the code below and replace the following and replace all the my* with your own values, but keep the event name as it is.

namespace MyVendor\MyExtension\EventListener;

use Evoweb\StoreFinder\Controller\Event\MapGetLocationsByConstraintsEvent;
use TYPO3\CMS\Core\Attribute\AsEventListener;

class MapGetSpecialLocationsListener
{
   #[AsEventListener('myextension_mapcontroller_fetchspeciallocations', MapGetLocationsByConstraintsEvent::class)]
   public function __invoke(MapGetLocationsByConstraintsEvent $event): void
   {
   }
}

Introduction of middleware 

With the introduction of the StoreFinderMiddleware it's possible to integrate a headless version of the map.

The middleware provides categories and locations. In addition its possible to use location and fulltext search in combination with category filtering.

Only the endpoints are provided. You need to implement the javascript yourself.

Preparation of data 

To modify the categories and locations events ModifyMiddlewareCategoriesEvent and ModifyMiddlewareLocationsEvent are provided.

As an example on how to use the ModifyMiddlewareLocationsEvent the listener ModifyMiddlewareLocationsListener is present.

Integration 

To use the middleware, it's important to include th Ajax.yaml in the site config

imports:
  - { resource: 'EXT:store_finder/Configuration/Routes/Ajax.yaml' }

Fields to output and conversion can be changed with TypoScript key plugin.tx_storefinder.ajax

Template example 

Below is an example on how to use the configuration and endpoints with your custom code.

<store-finder-map
    showSearch="{sf:bitwiseIf(a: settings.showBeforeSearch, b: 1, then: 1, else: 0)}"
    showList="{sf:bitwiseIf(a: settings.showBeforeSearch, b: 4, then: 1, else: 0)}"
    categoriesEndpoint="{f:uri.typolink(parameter: '/api/storefinder/categories/{cObjectData.uid}')}"
    locationsEndpoint="{f:uri.typolink(parameter: '/api/storefinder/locations/{cObjectData.uid}')}"/>

Arguments 

• fileName

  StorageId (most likely 1) and path and filename of excel file that should be imported relatively to the storage (fileadmin) Eg: 1:/user_upload/locations.xlsx

Options 

• --storagePid -s

  Page id of storage folder. Default is 1.

• --clearStorageFolder -c

  Flag if storage folder should be emptied before importing

• --columnMap -o

  Json encoded column map array.

  Default

  {"A":"import_id","B":{0:"name",1:"storeid"}},"C":"address","D":"city","E":"zipcode","F":"country","G":"state","H":"person","I":"url","J":"image"}

  Copied!

• --attributeMap -a

  Json encoded attribute map array.

  Default

  {"K":{"att1":1}}

  Copied!

• --categoryMap -t

  Json encoded attribute map array.

  Default

  {"L":{"cat1":1}}

  Copied!

Transformation 

• the first line will always be ignored.
• transformation is in order of attributes, categories, location fields.
• every column in one of the three maps is imported in a location field
• country, state, image, media, icon are special fields country is a ISO3 code for a country and is stored in the country field as uid of the static_country record state is a zones code for a state and is stored in the state field as uid of the static_country_zones record image is a file path and name relative to file storage like 1:/user_upload/test.jpg and is referenced by sys_file_reference media is a file path and name relative to file storage like 1:/user_upload/video.mp4 and is referenced by sys_file_reference * icon is a file path and name relative to file storage like 1:/user_upload/icon.jpg and is referenced by sys_file_reference
• references to attributes, categories and files are removed if not present any more

Importing constraints 

• if import_id is set updating locations is possible
• it's always an incremental import
• if a full import should be performed the flag clearStorageFolder needs to be true, then the folder gets emptied before importing
• it's possible to import multiple references for attributes, categories and files
• by adding multiple columns containing file information: H, I, J "1:/user_upload/image1.jpeg","1:/user_upload/image1.jpeg","1:/user_upload/image1.jpeg" and change the configuration object like: {..."H":"image","I":"image","J":"image"...} The result is, that the locations has three images referenced

Examples of import command calls 

vendor/bin/typo3 storefinder:import --storagePid=202 --clearStorageFolder=1 filename

vendor/bin/typo3 storefinder:import --storagePid=4 --columnMap="{\"A\":\"import_id\",\"B\":\"name\",\"D\":\"city\"}" "1:/user_upload/ExportExcel.xlsx"

vendor/bin/typo3 storefinder:import \
  -c \
  --storagePid=2
  -o"{\"A\":\"import_id\",\"B\":\"name\",\"D\":\"city\"}" \
  "1:/user_upload/ExportExcel.xlsx"

Version 6.0.0 

<f:if condition="{sf:format.binaryAnd(base: 1, content: settings.showBeforeSearch)} == 1">

<sf:bitwiseIf a="{comparisonValue}" b="1">

04. December 2025 

The validation got an overhaul.

The modification it self was moved from the controller to the ModifyValidator service.

Validator namespaced shorthand got dropped in EXT:extbase, that's why only fully qualified namespaced validator class names are possible. The TypoScript was adapted accordingly.

The services namespaces got changed from Serviceto Services.

02. August 2024 

Replacing CountryRepository with CountryProvider

CountryRepository relayed on EXT:static_info_tables. As the core now is providing countries, the installation of that extension is not needed anymore.

An install tool migration to update the locations records is provided.

The sf:form.selectCountries viewHelper got dropped in favor of f:form.countrySelect. If you override a partial. You need to get the country select in sync with the provided one.

20. Mai 2024 

Result of location repository functions are either location model or array of location models.

Removed QueryBuilderHelper. The queryBuilder gets assignment to the query as statement and let Extbase take care of the conversion.

The country selector does not take string indexes anymore. If you used isoCodeA2 or isoCodeA3 in TypoScript before, you need to change your Search.html partial to only use {constraint.country.uid} as value and set the optionValueField="uid" argument of the sf:form.selectCountries ViewHelper.

The countryValueType setting in TypoScript is dropped.

Refactor geocode service to use TYPO3CMSCoreHttpClientGuzzleClientFactory instead of creating of using HttpAdapterGuzzle7Client directly

17. February 2023 

29. August 2022 

The import command is refactored and the arguments and options are cleaned up. Please read the docs for the changes

15. February 2021 

01. Mai 2020 

03. October 2019 

31. January 2019 

Drop already deprecated GeocodeLocationsTask in favor of GeocodeLocationsCommandController

Deprecate GeocodeLocationsCommandController to be replaced with GeocodeLocationsCommand once support for TYPO3 8.7 gets dropped.

18. May 2019 

As of now configuration.insertSingleViewInto is deprecated and removed.

Please use configuration.renderSingleViewCallback instead. This should contain a callback function which renders the single view element. As parameter location and infoWindowTemplate are available. In addition a configuration.handleCloseButtonCallback should be provided.

Example:

configuration.renderSingleViewCallback = function (location, infoWindowTemplate) {
      location['information']['staticMapCenter'] = encodeURIComponent(location.information.address) + ',+'
         + encodeURIComponent(location.information.zipcode) + ',+'
         + encodeURIComponent(location.information.city) + ',+'
         + encodeURIComponent(location.information.country);

      html = infoWindowTemplate.render(location.information);

      var $singleView = $('.yourSingleView');
      if ($singleView.hasClass('show')) {
         $singleView.hide();
         $singleView.removeClass('show');
      }
      $singleView.html(html);
      $singleView.show();
      $singleView.addClass('show');

      $('body').trigger('initializeTabs');
};

configuration.handleCloseButtonCallback = function (button) {
      var $singleView = button.parents('.yourSingleView');
      $singleView.hide();
      $singleView.removeClass('show');
}

10. January 2019 

As of the location model does not escapeJsonString any properties anymore. With this getNameRaw and getCityRaw are dropped.