Regions
Regions let you show visitors only the events and prices that are relevant to them, such as one list for /region-US/, another for /region-GB/ and another for /region-DE/. You set up regions in Arlo, map them in the plugin, and the plugin then keeps each visitor's lists, event pages and prices in their region.
Regions are optional. If your platform has a single region, you can leave the plugin's regions empty and show one global list. See Using no regions. If your platform has more than one region, map them.
Contents
- What regions cover
- Mapping your Arlo regions
- Regional addresses
- How the plugin remembers a visitor's region
- Letting visitors choose a region
- Managing the experience yourself
- Pricing and currencies
- Using no regions
What regions cover
Regions apply to the things you schedule and sell: event templates, events, online activities and their offers each carry the region they belong to in Arlo. So regions affect:
- the catalogue, schedule, upcoming events, event search and online activities lists, and any custom shortcode of those types;
- the single event pages, such as
/events/123-course-name/region-US/.
Venues and presenters are not regional. They have no region of their own, so the venue and presenter lists and pages have no /region- segment and show the same content to everyone.
Mapping your Arlo regions
You map regions on the Regions tab of the Arlo settings. Add a row for each region, with a Region ID and a Region name. The ID must be the same as the region ID on your Arlo platform, because that is how each event is matched to a region. The plugin does not fetch your regions from Arlo, so enter them yourself. See Settings: Regions for the options, and save and then synchronize after any change.
- The first region is the default. It is the region a new visitor gets.
- A list with no events in the visitor's region shows the "No events to show" text. If a course is not offered in the visitor's region, use [arlo_no_event_in_region] in your Event template to show a message on its page.
Regional addresses
When regions are mapped, the plugin adds the region to the address of every regional list and event, as a region- segment followed by the region ID:
| Page | Example address |
|---|---|
| Catalogue | /events/region-US/ |
| Catalogue with a category | /events/region-US/cat-12/ |
| Upcoming events | /upcoming/region-GB/ |
| A single event | /events/123-course-name/region-DE/ |
The links the plugin builds, such as categories, paging and event links, carry the visitor's region. A region in the query string, such as ?arlo-region=US, is also accepted. A region ID that is not in your mapping is ignored.
See Pages and routing for how the rest of the address is built.
How the plugin remembers a visitor's region
The plugin stores the visitor's region in a cookie named arlo-region. It is set for the whole site and lasts 30 days.
- A first-time visitor opens a regional page without a region in the address, such as
/events/. The plugin saves the first region in the cookie and redirects them to that region's address,/events/region-EU/if EU is first. - A visitor who opens an address with a region in it, such as
/events/region-US/, has the cookie updated to that region. - A returning visitor who opens a regional page without a region is redirected to the region in their cookie.
- On a page that is not regional, such as the venues list, the plugin saves the first region if there is no cookie yet, and does not redirect.
The plugin does not work out a visitor's region from their location, IP address or browser language. It only uses the address and the cookie, and otherwise the first region. If you want a first-time visitor sent to a region that suits them, you can do that yourself. See Managing the experience yourself.
To change how long the cookie lasts, see arlo_region_cookie_time.
Letting visitors choose a region
The plugin gives you a region dropdown to put on your pages:
- [arlo_template_region_selector] in the catalogue, schedule, upcoming, online activities and event templates. The bundled themes use it. [arlo_upcoming_region_selector] gives the same dropdown in the upcoming events template.
- [arlo_template_search_region_selector] in the event search template.
- The Region selector widget, to put the dropdown in a widget area.
The dropdown lists the regions you mapped, in the order you set them. Choosing one saves the region in the cookie and moves the visitor to the same page in that region. There is no "all regions" option. You can style the dropdown with CSS, or build your own from the same region- addresses.
Managing the experience yourself
If your site already has its own way of choosing a region, such as a welcome page for a first-time visitor, you can fit the plugin around it with two WordPress filters. Put the code in a must-use plugin or a site-specific plugin, not in the Arlo plugin, which would lose it on the next update.
arlo_region_redirect_location
Runs just before the plugin redirects a visitor to a regional address. You can cancel the redirect or send the visitor somewhere else, for example your own region chooser. It also tells you whether the visitor had a saved region or got the default, so you can treat a first visit differently. The Customizing region redirects page has the arguments, return values and examples, including cancelling the redirect for first-time visitors.
arlo_region_cookie_time
Sets how long the plugin keeps the arlo-region cookie.
Structure
add_filter( 'arlo_region_cookie_time', function ( $seconds ) {
return $seconds;
} );
| Argument | Type / values | Description |
|---|---|---|
| $seconds | Integer | How many seconds from now the cookie expires. The default is 2592000, which is 30 days. |
Example
Remember a visitor's region for one year:
<?php
/**
* Plugin Name: Site Arlo Region Cookie
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
add_filter( 'arlo_region_cookie_time', function () {
return YEAR_IN_SECONDS;
} );
Pricing and currencies
Prices come from the offers on your events and online activities. Each offer has its own amount and currency, and belongs to a region. In Arlo, a region has one currency, so a region is also how you set the currency a visitor sees. The plugin shows one currency on a page when regions are mapped, so your platform can sell in several currencies without them being listed together, such as USD, EUR and CAD prices in the same list.
Use regions to keep your regional pricing and regional currencies apart. When a visitor is in a region, every price on the page comes only from that region's offers, so it appears in that region's currency. For example, with regions US, DE and CA mapped:
| Region | Address | Prices shown |
|---|---|---|
| US | /events/region-US/ | US dollars, from the US offers |
| DE | /events/region-DE/ | Euros, from the DE offers |
| CA | /events/region-CA/ | Canadian dollars, from the CA offers |
The visitor changes currency by changing region, with the region selector.
This applies to every shortcode that shows a price or an offer: [arlo_event_template_advertised_price], [arlo_event_price], [arlo_event_offers], [arlo_upcoming_offer] and [arlo_oa_offers], and to the prices and currency in the event and online activity rich snippets.
- Create a region in Arlo for each currency you sell in, and map those regions in the plugin. A region's currency is set in Arlo, not in the plugin. The plugin shows the amount and currency of each offer as Arlo sends it, and does not convert between currencies.
- When regions are mapped, the "From" price on a list is the lowest offer in the visitor's region, so it is in one currency.
- With no regions mapped, multiple currencies are not supported. Arlo still sends every region's offers and the plugin stores them, but there is no region to choose a currency from, and the plugin does not use the default region instead. Prices from different regions can then appear on the same page. If you sell in more than one currency, map your regions.
Using no regions
You do not have to use regions. If your platform has a single region, leave the Regions tab empty and the plugin shows your events as one global list. Your Arlo data is still imported, and each event keeps its region in the plugin's tables.
With no regions mapped, the plugin turns the regional behaviour off as one piece, so there is nothing left half on:
- The region dropdown does not appear. The selector shortcodes output nothing, so your templates need no change. The Region selector widget has no dropdown to show, so remove it from your widget areas.
- There are no regional redirects and no region cookie.
- The links the plugin builds have no
/region-segment, such as/events/and/events/123-course-name/. - Nothing is filtered by region. Every list shows all of your events together. The plugin does not fall back to the default region: the first region is used only when regions are mapped, to choose where a new visitor goes.
Also note:
- An address that still has a
region-segment, such as an old link, still loads, and the region is ignored. - If your Arlo platform has more than one region, map them. Your platform's regional data is still imported, but without a mapping the plugin cannot tell the regions apart or choose between them. Events from every region appear in one list, and so do their prices. Leaving the regions unmapped is only supported when each of your courses is available in a single region. See Pricing and currencies.