Pages and routing

The Arlo plugin has a fixed set of global shortcodes, one for each kind of Arlo page: the catalogue, schedule, upcoming events and so on. Each one is designed to be mapped to one page in your WordPress site. The page's address is the address of that kind of page, and the page body holds the shortcode.

Contents

• How it fits together
• List pages and single pages
• The default pages and routes
• Changing a route
• How single page addresses are built
• Pages you do not need
• Checking a page is mapped correctly
• Extending the set with custom shortcodes
• One global shortcode per page

How it fits together

1. A global shortcode, such as [arlo_event_template_list], represents one kind of page.
2. A host page is the WordPress page you map it to. Its title, slug and address are yours to choose, and its body normally holds just the shortcode.
3. A template belongs to each shortcode. It holds the HTML and template shortcodes that build the page whenever the global shortcode is used. See Templates.

When you activate the plugin it creates a page for each built-in global shortcode, puts the shortcode in the body, and maps the page to that shortcode on the Pages tab. A page that already exists with the same slug is not changed, and you map it yourself.

List pages and single pages

Arlo has two kinds of page:

• List pages (for example, /events/) show many items, usually with filters and paging: the catalogue, schedule, upcoming events, event search, online activities, presenters and venues. Each has a host page and a global shortcode.
• Single pages (for example, /events/435-introduction-to-management/) show one item: an event template (a course), a presenter or a venue. An event page covers all the running dates of its course. The importer creates a WordPress post for each, and the Event, Presenter and Venue templates build them. You edit their templates, but you do not map them to a page.

You map a list page because there is exactly one of it, so you choose which WordPress page carries it. A single page is different: there is one for every event template (course), presenter and venue, created and removed by the importer as your Arlo data changes, so there is no single page to choose. Instead, each kind of single page belongs to a list page, and is mapped by following it:

• The Catalogue page is the parent of the event pages, the Venues page of the venue pages, and the Presenters page of the presenter pages.
• When you map or rename the parent list page, you also set the base of every one of its single pages. The Event, Presenter and Venue sub-tabs on the Pages tab show the resulting address, but you change it by changing the parent page.
• This is why the parent's route matters beyond the list itself. See How single page addresses are built.

The default pages and routes

The plugin creates these pages as drafts. Publish the ones you use before they can be visited. You do not have to use them all, and can leave any of them unpublished with its host page set to (None). The exception is Events, Venues and Presenters: keep those published and mapped whenever you use event, venue or presenter pages, even if you do not use their lists. See Pages you do not need.

Page title	Default route	Shortcode in the page	Kind
Events	/events/	[arlo_event_template_list]	List (the catalogue)
Schedule	/schedule/	[arlo_schedule]	List
Upcoming Events	/upcoming/	[arlo_upcoming_list]	List
Event search	/eventsearch/	[arlo_event_template_search_list]	List (search results)
Online Activities	/oa/	[arlo_onlineactivites_list]	List
Presenters	/presenters/	[arlo_presenter_list]	List, parent of the single presenter pages
Venues	/venues/	[arlo_venue_list]	List, parent of the single venue pages

Pages for a single course, presenter or venue are not in this table because there is one for every item, so they cannot be mapped to a page. They follow their parent list page's route instead, as described in List pages and single pages.

Changing a route

The route is the address of the WordPress page. To change it, edit the page in WordPress and change its Slug, for example from events to courses to move the route from /events/ to /courses/. Changing only the page title does not change its existing slug. You can also map a different existing page on the Pages tab.

When your platform uses regions, the regional lists and events add a /region-XX/ segment after the route, such as /events/region-US/. Venues and presenters are not regional and have no such segment.

• Choose Save Changes on the Arlo settings after changing a slug or mapping. The plugin refreshes its address rules when the settings are saved and after each import completes, not when you edit the page. Until then the new address, and the event addresses under it, return "Page not found", while the old ones keep working.
• The page must be published. While it is a draft or pending, the plugin cannot use its address, so the list page returns "Page not found". See Pages you do not need before unpublishing the Catalogue.
• If you change a route on a live site, redirect the old address to the new one so existing links keep working.

How single page addresses are built

Three of the list pages are the parent of a kind of single page. A single page does not have its own mapping, so it takes its base address from its parent's route (it "inherits" it) and adds an identifier and a name:

Parent list page	Single page	Example address
Catalogue (/events/)	Event	/events/123-introduction-to-first-aid/
Venues (/venues/)	Venue	/venues/45-main-street-training-room/
Presenters (/presenters/)	Presenter	/presenters/17-jane-smith/

• The relationship follows the parent's slug. If you change the Catalogue page's slug to /courses/, event addresses become /courses/123-introduction-to-first-aid/.
• Event pages always live under the Catalogue, even when the visitor arrives from the schedule, event search or online activities pages.
• Keep the parent page published and mapped. If you unpublish or unmap the Catalogue, event pages stop working and return "Page not found". See Pages you do not need.

Pages you do not need

You do not have to use every global shortcode. The plugin creates and maps all of the default pages, but you only need the ones your site uses. A site that presents its courses through the schedule, for example, may not want a catalogue.

Schedule, Upcoming, Event search and Online activities

These lists have no single pages that depend on them, so you can drop one without affecting your event, venue or presenter addresses:

1. On the Pages tab, set the sub-tab's Host page to (None). This only removes the mapping. It does not change whether the page is published, which you manage in WordPress, because the page may hold other content you want to keep.
2. In WordPress, unpublish the page. If you want to keep the page published for other content, remove the global shortcode from its body instead.

• The Catalogue, Event, Venue and Presenter pages keep working. One link crosses between pages: the Venue and Venue list templates in several bundled themes use [arlo_venue_events_link] for "View upcoming" and "View scheduled" buttons. It outputs nothing when its target, Upcoming events or Schedule, has no host page, so dropping one of those pages removes its button. That is usually what you want. If you rely on the button, keep the page mapped, or edit your venue templates first.
• If you use the Search widget or a search form, keep Event search published and mapped, because they send visitors to that page.

Catalogue, Venues and Presenters

These are the parents of the event, venue and presenter pages, so be more careful. You can turn the list off and keep the single pages working:

1. Keep the host page published and mapped on the Pages tab.
2. Remove the global shortcode from the page body, so the page no longer shows the list. You can put your own content there, such as a short message or a link to the schedule, or redirect the address elsewhere with your usual redirect tools.
3. Remove the page from your menus and links.

The list address then shows only the page's own content and no Arlo list, while the event pages keep working at /events/123-course-name/. The mapping check warns that the page is missing its shortcode. That is expected when the page is switched off on purpose.

Venues and Presenters work the same way, if you still use the venue or presenter pages: keep the host page published and mapped, and remove the shortcode.

Checking a page is mapped correctly

On the Pages tab, each time you choose a host page the plugin checks that the page body contains the matching global shortcode, and shows the result next to the dropdown. It is a warning, not a block: you can still save, but a page with the wrong shortcode can break key parts of the page, such as filtering and paging, because the list is not the one that the address rules expect.

Result	Meaning
Page contains the expected shortcode	The mapping is correct.
Warning naming the shortcode	The page is published and has content, but not this shortcode. Edit the page and add it, or choose a different page.
Selected page is not published	Publish the page. The check needs a published page, so it cannot confirm the shortcode on a draft, scheduled or pending page.
Shortcode check unavailable	The page has an empty body, for example because a page builder or another plugin manages it. Check the shortcode is on the page yourself.

Choosing the same page for two page types is flagged separately. See Host pages.

Extending the set with custom shortcodes

The built-in set gives you one page of each kind. When you need another one, add a custom shortcode on the New sub-tab of the Pages tab. A custom shortcode is a variant of a built-in type (Catalogue, Schedule, Upcoming, Online Activities, Presenters or Venues), and you map it to its own new page, just like a built-in one. It behaves like its type and accepts the same attributes, and it has:

• its own shortcode, such as [arlo_firstaid];
• its own host page, and so its own route;
• its own template, which starts from the default template for its type (not from any changes you made to the original page's template) and can then be changed without affecting the original page;
• its own Page filtered by settings.

Example: a landing page for one category

A training provider has a main catalogue at /events/ that lists every course. They also run a marketing campaign for first aid, and want a page at /first-aid-courses/ that opens on the first aid courses, with its own layout and wording. They do not want to change the main catalogue. To do this they:

1. Add a custom shortcode on the Pages tab, named firstaid with the type Catalogue. The shortcode is [arlo_firstaid].
2. Create a WordPress page titled "First aid courses" with the slug first-aid-courses, and put [arlo_firstaid category="12"] in its body, where 12 is the Arlo ID of the First Aid category. This is the page's default category.
3. Publish the page, then choose it as the Host page on the new Firstaid sub-tab. The plugin checks the page contains [arlo_firstaid].
4. Edit the new sub-tab's template to suit the campaign, for example a simpler list without the category sidebar. The original Catalogue template is unchanged.

Now /events/ still lists everything with the original template, and /first-aid-courses/ opens on the first aid courses with its own. Filters and paging work on each page independently, because each page holds one global shortcode.

The category on the shortcode also limits the page's own category filter to that category, so visitors are not offered others there. It is still a default and not a lock: a category in the address, such as /first-aid-courses/cat-13/, overrides it.

Other ways to use a custom shortcode:

• An Upcoming variant for one city, using location="Sydney", with a template that leaves out the location column.
• A Catalogue variant for in-house or corporate courses, using templatetag to start from the templates with that tag in Arlo.
• A Schedule or Upcoming variant with a compact template for a landing page.

A default filter can go on the shortcode, as in the example, or in Page filtered by on the sub-tab. A filter in the address overrides the same filter on the shortcode, and a filter on the shortcode overrides Page filtered by. See Filtering.

• A custom page's address follows the same rules as its base type. A Catalogue variant understands the same filter and paging segments as the main catalogue, for example /first-aid-courses/page/2/.
• Links to single event pages still point to the main Catalogue, such as /events/123-course-name/, not to the custom page.
• Keep one shortcode on each page. Do not add [arlo_firstaid] to the main Events page, or the other way round.

One global shortcode per page

We do not recommend putting more than one global shortcode on a page, and it is not supported. This matters most for list pages with filters or paging.

The reason is that a page has one address and the plugin reads it once. When a visitor opens /events/cat-12/page/2/, the plugin's address rule for the Catalogue page picks out the filters and page number and stores them for the request. Every Arlo shortcode on that page then reads the same stored values. Because of that:

• There is only one set of filters and one page number for the whole request. Two lists cannot each apply their own, so a visitor's filter or page change affects both.
• The address rule belongs to the page's own type. Each type accepts different filters: the upcoming events address understands venue, presenter and event tag, but the schedule address does not, and the presenters and venues addresses only understand paging. A second shortcode of a different type is handed values that are not designed for it, so its filters and paging do not work reliably.
• Filter and paging links are built from the page's own address, so they always change the type the page is mapped to.

To show the same kind of list in more than one place, or with a different fixed filter, create a custom shortcode and give it its own page. To show a short list in a sidebar or footer, use a widget.