📦 BOX NOW Global Widget

The BOX NOW Global Widget provides an interactive map interface for displaying locker locations. This guide covers all configuration options and implementation methods.

🌐 Widget Variants

The widget is available in two implementation formats:

🖼️ IFrame Integration

https://map.boxnow.gr/iframe.html

Perfect for embedding directly into your webpage content.

🔗 Popup Integration

https://map.boxnow.gr/popup.html

Ideal for modal dialogs or overlay implementations.

⚙️ Configuration Parameters

🔧 Required Parameters

These parameters must be provided for the widget to function:

Parameter	Type	Description	Example Values
countryCode	String	Target country/countries	"gr", "bg,hr", "gr,bg,hr,cy"
language	String	Display language	"gr", "bg", "en", "hr", "si"
partnerId	String	Your unique partner identifier	"your-partner-id"

🗺️ Country Codes

Support for multiple Balkan countries:

• gr - Greece 🇬🇷
• bg - Bulgaria 🇧🇬
• hr - Croatia 🇭🇷
• si - Slovenia 🇸🇮
• en - United Kingdom 🇬🇧

You can combine multiple countries: gr,bg,hr,cy,si

🌍 Languages

Available in local languages:

• gr - Greek
• bg - Bulgarian
• hr - Croatian
• si - Slovenian
• en - English

---

🎛️ Optional Parameters

Enhance your widget with these optional configurations:

♿ Accessibility

Parameter	Values	Default	Description
a11y	"yes", "no"	"no"	Enables accessibility-friendly UI/UX

🗺️ Map Display

Parameter	Values	Default	Description
islands	"yes", "no"	"yes"	Show/hide island locations
gps	"yes", "no"	"yes"	Enable GPS positioning
zip	String	-	Center map on ZIP code (when gps="no")

🧭 Behavior & Navigation

Parameter	Values	Default	Description
autoselect	"yes", "no"	"yes"	Auto-select first available locker
autoclose	"yes", "no"	"no"	Auto-close after selection
navigate	"yes", "no"	"no"	Enable navigation mode

---

💡 Best Practices & Recommendations

🔗 For Popup Implementation

✅ Recommended Settings:
- autoselect="no"
- autoclose="yes"

🧭 For Navigation Mode

✅ Required Settings:
- navigate="yes"
- autoselect="no"

🎯 Default Behavior

• Without partnerId: Shows lockers with large compartments
• With partnerId: Shows partner-specific lockers

---

📋 Implementation Examples & Live Demos

🖼️ Basic IFrame Integration

<iframe
  src="https://map.boxnow.gr/iframe.html?countryCode=gr&language=gr&partnerId=your-partner-id"
  width="100%"
  height="500px"
>
</iframe>

🎮 Try it live: Open Iframe Demo

---

🔗 Basic Popup Configuration

<iframe
  src="https://map.boxnow.gr/popup.html?countryCode=gr,bg,hr&language=gr&partnerId=your-partner-id&autoselect=no&autoclose=yes"
  width="100%"
  height="500px"
>
</iframe>

🎮 Try it live: Open Popup Demo

---

🧭 Navigation Mode Example

https://map.boxnow.gr/iframe.html?countryCode=gr&language=gr&navigate=yes&autoselect=no

🎮 Try it live: Open Navigate Demo

---

🌍 Multi-Country Setup with Accessibility

https://map.boxnow.gr/iframe.html?countryCode=gr,bg,hr,cy&language=en&partnerId=your-partner-id&a11y=yes

---

📍 Fixed Location (ZIP-based) Demo

https://map.boxnow.gr/iframe.html?countryCode=gr&language=en&partnerId=your-partner-id&gps=no&zip=10681

---

🔍 Parameter Reference Table

Parameter	Required	Type	Default	Values	Description
countryCode	✅	String	-	gr, bg, hr, si, cy (combinable)	Target countries
language	✅	String	-	gr, bg, hr, si, en	Display language
partnerId	✅	String	-	Any string	Partner identifier
a11y	❌	String	"no"	yes, no	Accessibility mode
islands	❌	String	"yes"	yes, no	Show island locations
zip	❌	String	-	Valid ZIP code	Center map location
gps	❌	String	"yes"	yes, no	GPS positioning
navigate	❌	String	"no"	yes, no	Navigation mode
autoselect	❌	String	"yes"	yes, no	Auto-select first locker
autoclose	❌	String	"no"	yes, no	Auto-close after selection

---

🚀 Quick Start Checklist

1. Choose your implementation 🖼️ IFrame or 🔗 Popup
2. Set required parameters: countryCode, language, partnerId
3. Configure for your use case:
   • 🔗 Popup? Set autoselect="no" and autoclose="yes"
   • 🧭 Navigation? Set navigate="yes" and autoselect="no"
   • ♿ Accessibility? Set a11y="yes"
4. Test your configuration with the provided live demos
5. Deploy and monitor user interactions

---

⚠️ Container Must Be Visible Before the Map Loads

The map fills its host iframe viewport. Whether you embed iframe.html / popup.html directly, or load it through the v5.js client (which inserts an iframe with width: 100%; height: 100% into your parentElement), that host must have real layout size when the map loads.

If the container is hidden or 0×0 at that moment (for example display: none or a collapsed section), the map initializes with incorrect dimensions and may render blank or broken.

This must be handled on the e-shop / integrator side. The widget cannot reliably recover from a zero-size parent after load.

Rule

Make sure the container is visible and has real dimensions before the map iframe is created or shown. How you structure your UI is up to you — the important part is the order: size the container first, then load the map.

Avoid

• Creating the iframe while the parent is hidden (display: none, visibility: hidden) or has 0×0 size
• Pre-creating the iframe in a hidden container and only revealing it later
• Assuming the map will correct itself after the container becomes visible

Example (illustrative only)

One possible approach when embedding the map URL directly — show the container, then create the iframe. Adapt this to your own page structure; you do not have to use this exact pattern. If you use the v5.js client instead, the same order applies: size/show #boxnowmap before the client creates the iframe (on button click, or immediately if autoshow: true).

<div id="boxnowmap" style="display: none; width: 100%; height: 500px;"></div>

<script type="text/javascript">
  function showBoxNowMap() {
    var wrapper = document.getElementById('boxnowmap')

    // Display the container before creating the iframe
    wrapper.style.display = 'block'

    if (wrapper.children.length) {
      return
    }

    var iframe = document.createElement('iframe')
    iframe.id = 'boxnow-iframe'
    iframe.src =
      'https://map.boxnow.bg/popup.html?gps=yes&autoselect=no&autoclose=no&countryCode=bg&language=bg&zip=1000'
    iframe.width = '100%'
    iframe.height = '500px'
    iframe.style.border = '0'
    iframe.allow = 'geolocation'

    wrapper.appendChild(iframe)
  }
</script>

---

🆘 Troubleshooting

Common Issues

Widget not loading?

• ✅ Verify all required parameters are provided
• ✅ Check country code format (comma-separated, no spaces)
• ✅ Ensure language matches available options

Map blank or broken after opening?

• ✅ Ensure the parent container is visible and has real width/height before the iframe is created (see Container Must Be Visible Before the Map Loads)

GPS not working as expected?

• ✅ Set gps="no" and provide zip parameter for fixed location
• ✅ Without ZIP, geo-IP will determine location

Navigation mode issues?

• ✅ Always use navigate="yes" with autoselect="no"

---

For additional support or custom implementations, please contact the BOX NOW development team.