SmartMaps Address Autocomplete: Technical Details

Technical details of the SmartMaps Address Autocomplete plugin: flow, plugin structure, configuration keys, Twig blocks, Storefront JavaScript, and the absent admin, ACL and database parts.

Deutsche Version

Back to overview

Technical details

This documentation always describes the latest published version.

Key facts

Property	Value
Composer package	`mmd/smart-maps-integration`
Plugin class	`Mmd\SmartMapsIntegration\MmdSmartMapsIntegration`
Plugin name for `bin/console`	`MmdSmartMapsIntegration`
Namespace	`Mmd\SmartMapsIntegration`
Requirements	PHP >= 8.2, `shopware/core` ~6.7.0
Configuration keys	`MmdSmartMapsIntegration.config.apiKey`, `.enabled`, `.countryFilter`

Flow

graph TD
    A["Storefront page is rendered"] --> B["StorefrontSubscriber"]
    B --> C{"Route in the list?"}
    C -->|"No"| D["Do nothing"]
    C -->|"Yes"| E["SmartMapsConfigService reads system config"]
    E --> F{"Enabled and key valid?"}
    F -->|"No"| D
    F -->|"Yes"| G["Set Twig parameters"]
    G --> H["base.html.twig loads CSS and JS from SmartMaps"]
    G --> I["address-form.html.twig wraps the form"]
    H --> J["Inline script initialises autocomplete"]
    I --> J

graph LR
    A["Customer types"] --> B["SmartMaps library"]
    B --> C["Suggestions"]
    C --> D["Customer selects"]
    D --> E["Fill fields"]
    E --> F["input and change events"]

Plugin structure

File	Purpose
`src/MmdSmartMapsIntegration.php`	Plugin class, no logic of its own
`src/Subscriber/StorefrontSubscriber.php`	Listens to `StorefrontRenderEvent`, filters by route and sets the Twig parameters
`src/Service/SmartMapsConfigService.php`	Reads the settings per sales channel from the system configuration
`src/Struct/SmartMapsConfig.php`	Value object with the `isConfigured()` check
`src/Resources/config/config.xml`	Admin configuration
`src/Resources/views/storefront/base.html.twig`	Loads CSS and JS from SmartMaps and contains the initialisation script
`src/Resources/views/storefront/component/address/address-form.html.twig`	Wraps the address form with the data attributes
`src/Resources/app/storefront/src/main.js`	Registers the JS class `SmartMapsAutocomplete` on the selector `[data-smartmaps-autocomplete]`

Twig parameters

Parameter	Content
`mmdSmartMapsConfig`	`enabled` (bool) and `countryFilter` (string)
`mmdSmartMapsApiKey`	the trimmed API key

Both are only set when the route is in the list and the configuration is valid.

Initialisation in the browser

There are two paths that bind the autocomplete to a street field: the inline script in base.html.twig and the registered JS class SmartMapsAutocomplete. Before initialising, the inline script checks the attribute dataset.smartmapsInitialized on the street field and skips fields that are already initialised, the JS class has no such check.

Error behaviour

The subscriber catches every exception and ignores it, so a plugin error never disturbs the storefront. Errors in the browser end up in the console, from the inline script with the prefix [SmartMaps] and from the JS class with the prefix [SmartMapsAutocomplete].

What the plugin does not provide

no admin UI besides the configuration card
no routes or API endpoints of its own
no database migrations or entities
no snippets or translation files of its own (the configuration texts are in config.xml)
no ACL privileges, the configuration follows the usual permissions for system settings
no console commands and no extension points for other plugins